Update .travis.yml

* Change __BORLANDC__ to BOOST_BORLANDC, which is defined in Boost config for the Embarcadero non-clang-based compilers.

* Restored a Borland check.

* Specify std:: for all standard identifiers and remove 'using namespace std:'.

* Removed std:: from C header abort call.

* Moved 'using namespace std;' after header file inclusions

.codecov.yml

@@ -0,0 +1,3 @@
+fixes:
+  - home/travis/build/*/boost-root/boost/::include/boost/
+  - home/travis/build/*/boost-root/libs/*/src/::src/

.travis.yml

@@ -0,0 +1,147 @@
+# Copyright 2016-2019 Peter Dimov
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at http://boost.org/LICENSE_1_0.txt)
+
+language: cpp
+
+dist: xenial
+
+branches:
+  only:
+    - master
+    - develop
+    - /feature\/.*/
+
+env:
+  matrix:
+    - BOGUS_JOB=true
+
+matrix:
+
+  exclude:
+    - env: BOGUS_JOB=true
+
+  include:
+    - os: linux
+      compiler: g++-4.4
+      env: TOOLSET=gcc COMPILER=g++-4.4 CXXSTD=98,0x
+      addons:
+        apt:
+          packages:
+            - g++-4.4
+          sources:
+            - ubuntu-toolchain-r-test
+
+    - os: linux
+      compiler: g++-4.6
+      env: TOOLSET=gcc COMPILER=g++-4.6 CXXSTD=03,0x
+      addons:
+        apt:
+          packages:
+            - g++-4.6
+          sources:
+            - ubuntu-toolchain-r-test
+
+    - os: linux
+      dist: bionic
+      compiler: g++-10
+      env: UBSAN=1 TOOLSET=gcc COMPILER=g++-10 CXXSTD=03,11,14,17,20 UBSAN_OPTIONS=print_stacktrace=1 LINKFLAGS=-fuse-ld=gold
+      addons:
+        apt:
+          packages:
+            - g++-10
+          sources:
+            - sourceline: "ppa:ubuntu-toolchain-r/test"
+
+    - os: linux
+      dist: trusty
+      compiler: /usr/bin/clang++
+      env: TOOLSET=clang COMPILER=/usr/bin/clang++ CXXSTD=03,11
+      addons:
+        apt:
+          packages:
+            - clang-3.3
+
+    - os: linux
+      dist: trusty
+      compiler: /usr/bin/clang++
+      env: TOOLSET=clang COMPILER=/usr/bin/clang++ CXXSTD=03,11
+      addons:
+        apt:
+          packages:
+            - clang-3.4
+
+    - os: linux
+      compiler: clang++-11
+      env: UBSAN=1 TOOLSET=clang COMPILER=clang++-11 CXXSTD=03,11,14,17,20 UBSAN_OPTIONS=print_stacktrace=1
+      addons:
+        apt:
+          packages:
+            - clang-11
+          sources:
+            - ubuntu-toolchain-r-test
+            - sourceline: 'deb https://apt.llvm.org/xenial/ llvm-toolchain-xenial-11 main'
+              key_url: 'https://apt.llvm.org/llvm-snapshot.gpg.key'
+
+    - os: linux
+      dist: bionic
+      compiler: clang++-libc++
+      env: UBSAN=1 TOOLSET=clang COMPILER=clang++-libc++ CXXSTD=03,11,14,17,2a UBSAN_OPTIONS=print_stacktrace=1
+      addons:
+        apt:
+          packages:
+            - libc++-dev
+
+    - os: freebsd
+      compiler: clang++
+      env: TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,17,2a
+
+    - os: osx
+      compiler: clang++
+      env: TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,1z ADDRMD=32,64
+      osx_image: xcode7.3
+
+    - os: osx
+      compiler: clang++
+      env: TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,1z ADDRMD=32,64
+      osx_image: xcode8.3
+
+    - os: osx
+      compiler: clang++
+      env: TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,1z ADDRMD=32,64
+      osx_image: xcode9.4
+
+    - os: osx
+      compiler: clang++
+      env: TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,1z
+      osx_image: xcode10.1
+
+    - os: osx
+      osx_image: xcode11.3
+      compiler: clang++
+      env: TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,1z
+
+    - os: osx
+      osx_image: xcode12.2
+      compiler: clang++
+      env: UBSAN=1 TOOLSET=clang COMPILER=clang++ CXXSTD=03,11,14,1z UBSAN_OPTIONS=print_stacktrace=1
+
+install:
+  - BOOST_BRANCH=develop && [ "$TRAVIS_BRANCH" == "master" ] && BOOST_BRANCH=master || true
+  - cd ..
+  - git clone -b $BOOST_BRANCH --depth 1 https://github.com/boostorg/boost.git boost-root
+  - cd boost-root
+  - git submodule update --init tools/boostdep
+  - cp -r $TRAVIS_BUILD_DIR/* libs/program_options
+  - python tools/boostdep/depinst/depinst.py program_options
+  - ./bootstrap.sh
+  - ./b2 headers
+
+script:
+  - |-
+    echo "using $TOOLSET : : $COMPILER ;" > ~/user-config.jam
+  - ./b2 -j3 libs/program_options/test toolset=$TOOLSET cxxstd=$CXXSTD variant=debug,release ${ADDRMD:+address-model=$ADDRMD} ${UBSAN:+cxxflags=-fsanitize=undefined cxxflags=-fno-sanitize-recover=undefined linkflags=-fsanitize=undefined define=UBSAN=1 debug-symbols=on} ${LINKFLAGS:+linkflags=$LINKFLAGS}
+
+notifications:
+  email:
+    on_success: always

Jamfile

@@ -0,0 +1,11 @@
+#  Boost.ProgramOptions Library Jamfile
+#
+#  Copyright (c) 2018 James E. King III
+#
+#  Use, modification, and distribution are subject to the
+#  Boost Software License, Version 1.0. (See accompanying file
+#  LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+# please order by name to ease maintenance
+build-project example ;
+build-project test ;

README.md

@@ -0,0 +1,37 @@
+Program Options, part of the collection of [Boost C++ Libraries](http://github.com/boostorg), allows for definition and acquisition of (name, value) pairs from the user via conventional methods such as command line and config file.  It is roughly analogous to getopt_long, but for use with C++.
+
+### License
+
+Distributed under the [Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt).
+
+### Properties
+
+* C++03
+* Requires Linking
+
+### Build Status
+(in progress...)
+
+|Branch          | Travis | Appveyor | codecov.io | Deps | Docs | Tests |
+|:-------------: | ------ | -------- | ---------- | ---- | ---- | ----- |
+|[`master`](https://github.com/boostorg/program_options/tree/master) | [![Build Status](https://travis-ci.org/boostorg/program_options.svg?branch=master)](https://travis-ci.org/boostorg/program_options) | [![Build status](https://ci.appveyor.com/api/projects/status/e0quisadwh1v7ok5/branch/master?svg=true)](https://ci.appveyor.com/project/vprus/program-options/branch/master) | [![codecov](https://codecov.io/gh/boostorg/program_options/branch/master/graph/badge.svg)](https://codecov.io/gh/boostorg/program_options/branch/master) | [![Deps](https://img.shields.io/badge/deps-master-brightgreen.svg)](https://pdimov.github.io/boostdep-report/master/program_options.html) | [![Documentation](https://img.shields.io/badge/docs-master-brightgreen.svg)](http://www.boost.org/doc/libs/master/doc/html/program_options.html) | [![Enter the Matrix](https://img.shields.io/badge/matrix-master-brightgreen.svg)](http://www.boost.org/development/tests/master/developer/program_options.html) 
+|[`develop`](https://github.com/boostorg/program_options/tree/develop) | [![Build Status](https://travis-ci.org/boostorg/program_options.svg?branch=develop)](https://travis-ci.org/boostorg/program_options) | [![Build status](https://ci.appveyor.com/api/projects/status/e0quisadwh1v7ok5/branch/develop?svg=true)](https://ci.appveyor.com/project/vprus/program-options/branch/develop) | [![codecov](https://codecov.io/gh/boostorg/program_options/branch/develop/graph/badge.svg)](https://codecov.io/gh/boostorg/program_options/branch/develop) | [![Deps](https://img.shields.io/badge/deps-develop-brightgreen.svg)](https://pdimov.github.io/boostdep-report/develop/program_options.html) | [![Documentation](https://img.shields.io/badge/docs-develop-brightgreen.svg)](http://www.boost.org/doc/libs/develop/doc/html/program_options.html) | [![Enter the Matrix](https://img.shields.io/badge/matrix-develop-brightgreen.svg)](http://www.boost.org/development/tests/develop/developer/program_options.html)
+ 
+### Directories
+
+| Name      | Purpose                        |
+| --------- | ------------------------------ |
+| `build`   | build script for link library  |
+| `ci`      | continuous integration scripts |
+| `doc`     | documentation                  |
+| `example` | use case examples              |
+| `include` | headers                        |
+| `src`     | source code for link library   |
+| `test`    | unit tests                     |
+
+### More information
+
+* [Ask questions](http://stackoverflow.com/questions/ask?tags=c%2B%2B,boost,boost-program_options): Be sure to read the documentation first to see if it answers your question.
+* [Report bugs](https://github.com/boostorg/program_options/issues): Be sure to mention Boost version, platform and compiler you're using. A small compilable code sample to reproduce the problem is always good as well.
+* [Submit Pull Requests](https://github.com/boostorg/program_options/pulls) against the **develop** branch. Note that by submitting patches you agree to license your modifications under the [Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt).  Be sure to include tests proving your changes work properly.
+* Discussions about the library are held on the [Boost developers mailing list](http://www.boost.org/community/groups.html#main). Be sure to read the [discussion policy](http://www.boost.org/community/policy.html) before posting and add the `[program_options]` tag at the beginning of the subject line.

appveyor.yml

@@ -0,0 +1,78 @@
+# Copyright 2016, 2017 Peter Dimov
+# Copyright (C) 2017, 2018 James E. King III
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at http://boost.org/LICENSE_1_0.txt)
+
+# When copying this to a new library, be sure to update the name of the library
+# in two places (once each at the top of install: and test_script:)
+
+version: 1.0.{build}-{branch}
+
+shallow_clone: true
+
+branches:
+  only:
+    - develop
+    - master
+
+matrix:
+  allow_failures:
+    - MAYFAIL: true
+
+environment:
+  global:
+    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
+    # see: http://www.boost.org/build/doc/html/bbv2/overview/invocation.html#bbv2.overview.invocation.properties
+    # to use the default for a given environment, comment it out; recommend you build debug and release however..
+    # on Windows it is important to exercise all the possibilities, especially shared vs static
+    # B2_ADDRESS_MODEL: address-model=64,32
+    # B2_LINK: link=shared,static
+    # B2_THREADING: threading=multi,single
+    B2_VARIANT: variant=release,debug
+    CXXSTD: 03
+
+  matrix:
+    - FLAVOR: Visual Studio 2017
+      TOOLSET: msvc-14.1
+      B2_ADDRESS_MODEL: address-model=64,32
+    - FLAVOR: Visual Studio 2013
+      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2013
+      TOOLSET: msvc-12.0
+    - FLAVOR:  mingw32
+      ARCH:    i686
+      B2_ADDRESS_MODEL: address-model=32
+      SCRIPT:  ci\mingw.bat
+    - FLAVOR:  mingw64
+      ARCH:    x86_64
+      B2_ADDRESS_MODEL: address-model=64
+      SCRIPT:  ci\mingw.bat
+    - FLAVOR: cygwin (64-bit)
+      ADDPATH: C:\cygwin64\bin;
+      B2_ADDRESS_MODEL: address-model=64
+      TOOLSET: gcc
+      MAYFAIL: true
+    - FLAVOR: cygwin (32-bit)
+      ADDPATH: C:\cygwin\bin;
+      B2_ADDRESS_MODEL: address-model=32
+      TOOLSET: gcc
+      MAYFAIL: true
+
+install:
+  - set SELF=program_options
+  - cd ..
+  - git clone -b %APPVEYOR_REPO_BRANCH% --depth 1 https://github.com/boostorg/boost.git boost-root
+  - cd boost-root
+  - git submodule update -q --init tools/boostdep
+  - git submodule update -q --init tools/build
+  - git submodule update -q --init tools/inspect
+  - xcopy /s /e /q %APPVEYOR_BUILD_FOLDER% libs\%SELF%
+  - python tools/boostdep/depinst/depinst.py --include example %SELF%
+  - cmd /c bootstrap
+  - b2 headers
+
+build: off
+
+test_script:
+  - set SELF=program_options
+  - PATH=%ADDPATH%%PATH%
+  - IF DEFINED SCRIPT (call libs\%SELF%\%SCRIPT%) ELSE (b2 libs/%SELF% toolset=%TOOLSET% cxxstd=%CXXSTD% %CXXFLAGS% %DEFINES% %B2_ADDRESS_MODEL% %B2_LINK% %B2_THREADING% %B2_VARIANT% -j3)

build/Jamfile

@@ -1,49 +0,0 @@
-
-subproject libs/program_options/build ;
-
-SOURCES = cmdline config_file options_description parsers variables_map 
-          value_semantic positional_options utf8_codecvt_facet convert
-          winmain
-;
-
-lib boost_program_options
-     : ../src/$(SOURCES).cpp
-     : # build requirements
-       [ common-names ] # magic for install and auto-link features
-       <include>$(BOOST_ROOT) <sysinclude>$(BOOST_ROOT)
-       std::locale-support
-     : debug release  # build variants
-     ;
-
-dll boost_program_options
-     : ../src/$(SOURCES).cpp
-     : # build requirements
-       [ common-names ]  # magic for install and auto-link features
-       <define>BOOST_ALL_DYN_LINK=1  # tell source we're building dll's
-       <runtime-link>dynamic  # build only for dynamic runtimes
-       <include>$(BOOST_ROOT) <sysinclude>$(BOOST_ROOT)
-       # The following really turns on static runtime linking
-       # which leads to runtime crashes when using DLL, so
-       # seem DLL is not usable on Metrowerks 8
-       # std::facet-support std::locale-support
-     : debug release  # build variants
-     ;
-
-install program_options lib
-     : <lib>boost_program_options <dll>boost_program_options
-     ;
-
-stage stage/lib : <lib>boost_program_options <dll>boost_program_options
-    :
-        # copy to a path rooted at BOOST_ROOT:
-        <locate>$(BOOST_ROOT)
-        # make sure the names of the libraries are correctly named:
-        [ common-names ]
-        # add this target to the "stage" and "all" psuedo-targets:
-        <target>stage
-        <target>all
-    :
-        debug release
-    ;
-
-# end

build/Jamfile.v2

@@ -3,18 +3,14 @@ project boost/program_options
     : source-location ../src 
     ;
 
-SOURCES = cmdline config_file options_description parsers variables_map 
-          value_semantic positional_options utf8_codecvt_facet
-          convert winmain
-      ;
-
-import os ;
-if [ os.name ] = NT
-{
-    linkage = <link>static ;
-}
-
-lib program_options
-  : $(SOURCES).cpp
-  : $(linkage)
+SOURCES =
+    cmdline config_file options_description parsers variables_map 
+    value_semantic positional_options utf8_codecvt_facet
+    convert winmain split
     ;
+
+boost-lib program_options
+    : $(SOURCES).cpp
+    : # See https://svn.boost.org/trac/boost/ticket/5049
+      <target-os>hpux,<toolset>gcc:<define>_INCLUDE_STDC__SOURCE_199901
+    ;

ci/build.sh

@@ -0,0 +1,19 @@
+#! /bin/bash
+#
+# Copyright 2017 James E. King III
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+#      http://www.boost.org/LICENSE_1_0.txt)
+#
+# Bash script to run in travis to perform a bjam build
+# cwd should be $BOOST_ROOT/libs/$SELF before running
+#
+
+set -ex
+
+# default language level: c++03
+if [[ -z "$CXXSTD" ]]; then
+    CXXSTD=03
+fi
+
+$BOOST_ROOT/b2 . toolset=$TOOLSET cxxstd=$CXXSTD $CXXFLAGS $DEFINES $LINKFLAGS $TESTFLAGS $B2_ADDRESS_MODEL $B2_LINK $B2_THREADING $B2_VARIANT -j3 $*

ci/codecov.sh

@@ -0,0 +1,43 @@
+#! /bin/bash
+#
+# Copyright 2017, 2018 James E. King III
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+#      http://www.boost.org/LICENSE_1_0.txt)
+#
+# Bash script to run in travis to perform codecov.io integration
+#
+
+###
+### NOTE: Make sure you grab .codecov.yml
+###
+
+# assumes cwd is the top level directory of the boost project
+# assumes an environment variable $SELF is the boost project name
+
+set -ex
+
+B2_VARIANT=debug
+ci/build.sh cxxflags=-fprofile-arcs cxxflags=-ftest-coverage linkflags=-fprofile-arcs linkflags=-ftest-coverage
+
+# switch back to the original source code directory
+cd $TRAVIS_BUILD_DIR
+
+# get the version of lcov
+lcov --version
+
+# coverage files are in ../../b2 from this location
+lcov --gcov-tool=gcov-7 --rc lcov_branch_coverage=1 --base-directory "$BOOST_ROOT/libs/$SELF" --directory "$BOOST_ROOT" --capture --output-file all.info
+
+# all.info contains all the coverage info for all projects - limit to ours
+lcov --gcov-tool=gcov-7 --rc lcov_branch_coverage=1 --extract all.info "*/boost/$SELF/*" "*/libs/$SELF/src/*" --output-file coverage.info
+
+# dump a summary on the console - helps us identify problems in pathing
+lcov --gcov-tool=gcov-7 --rc lcov_branch_coverage=1 --list coverage.info
+
+#
+# upload to codecov.io
+#
+curl -s https://codecov.io/bash > .codecov
+chmod +x .codecov
+./.codecov -f coverage.info -X gcov -x "gcov-7"

ci/coverity.sh

@@ -0,0 +1,42 @@
+#! /bin/bash
+#
+# Copyright 2017 James E. King III
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+#      http://www.boost.org/LICENSE_1_0.txt)
+#
+# Bash script to run in travis to perform a Coverity Scan build
+# To skip the coverity integration download (which is huge) if
+# you already have it from a previous run, add --skipdownload
+#
+
+#
+# Environment Variables
+#
+# COVERITY_SCAN_NOTIFICATION_EMAIL  - email address to notify
+# COVERITY_SCAN_TOKEN               - the Coverity Scan token (should be secure)
+# SELF                              - the boost libs directory name
+
+set -ex
+
+pushd /tmp
+if [[ "$1" != "--skipdownload" ]]; then
+  rm -rf coverity_tool.tgz cov-analysis*
+  wget https://scan.coverity.com/download/linux64 --post-data "token=$COVERITY_SCAN_TOKEN&project=boostorg/$SELF" -O coverity_tool.tgz
+  tar xzf coverity_tool.tgz
+fi
+COVBIN=$(echo $(pwd)/cov-analysis*/bin)
+export PATH=$COVBIN:$PATH
+popd
+
+ci/build.sh clean
+rm -rf cov-int/
+cov-build --dir cov-int ci/build.sh
+tar cJf cov-int.tar.xz cov-int/
+curl --form token="$COVERITY_SCAN_TOKEN" \
+     --form email="$COVERITY_SCAN_NOTIFICATION_EMAIL" \
+     --form file=@cov-int.tar.xz \
+     --form version="$(git describe --tags)" \
+     --form description="boostorg/$SELF" \
+     https://scan.coverity.com/builds?project="boostorg/$SELF"
+

ci/cppcheck.sh

@@ -0,0 +1,38 @@
+#! /bin/bash
+#
+# Copyright 2018 James E. King III
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+#      http://www.boost.org/LICENSE_1_0.txt)
+#
+# Bash script to run in travis to perform a cppcheck
+# cwd should be $BOOST_ROOT before running
+#
+
+set -ex
+
+# default language level: c++03
+if [[ -z "$CXXSTD" ]]; then
+    CXXSTD=03
+fi
+
+# Travis' ubuntu-trusty comes with cppcheck 1.62 which is pretty old
+# default cppcheck version: 1.82
+if [[ -z "$CPPCHKVER" ]]; then
+    CPPCHKVER=1.82
+fi
+
+pushd ~
+wget https://github.com/danmar/cppcheck/archive/$CPPCHKVER.tar.gz
+tar xzf $CPPCHKVER.tar.gz
+mkdir cppcheck-build
+cd cppcheck-build
+cmake ../cppcheck-$CPPCHKVER -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX=~/cppcheck
+make -j3 install
+popd
+
+~/cppcheck/bin/cppcheck -I. --std=c++$CXXSTD --enable=all --error-exitcode=1 \
+         --force --check-config --suppress=*:boost/preprocessor/tuple/size.hpp \
+         -UBOOST_USER_CONFIG -UBOOST_COMPILER_CONFIG -UBOOST_STDLIB_CONFIG -UBOOST_PLATFORM_CONFIG \
+         libs/$SELF 2>&1 | grep -v 'Cppcheck does not need standard library headers'
+

ci/mingw.bat

@@ -0,0 +1,50 @@
+::
+:: MinGW Build Script for Appveyor, leveraging the MSYS2 installation
+:: Copyright (C) 2018 James E. King III
+:: Distributed under the Boost Software License, Version 1.0.
+:: (See accompanying file LICENSE_1_0.txt or copy at http://boost.org/LICENSE_1_0.txt)
+::
+
+@ECHO ON
+SETLOCAL EnableDelayedExpansion
+
+:: Set up the toolset
+echo using gcc : %FLAVOR% : %ARCH%-w64-mingw32-g++.exe ; > %USERPROFILE%\user-config.jam
+SET UPPERFLAVOR=%FLAVOR%
+CALL :TOUPPER UPPERFLAVOR
+
+:: Install packages needed to build boost
+:: Optional: comment out ones this library does not need, 
+:: so people can copy this script to another library.
+
+FOR %%a IN ("gcc" "icu" "libiconv" "openssl" "xz" "zlib") DO (
+    c:\msys64\usr\bin\env MSYSTEM=%UPPERFLAVOR% c:\msys64\usr\bin\bash -l -c ^
+      "pacman --sync --needed --noconfirm %FLAVOR%/mingw-w64-%ARCH%-%%a" || EXIT /B
+)
+c:\msys64\usr\bin\env MSYSTEM=%UPPERFLAVOR% c:\msys64\usr\bin\bash -l -c ^
+  "pacman --sync --needed --noconfirm python3" || EXIT /B
+
+::
+:: Now build things...
+::
+
+c:\msys64\usr\bin\env MSYSTEM=%UPPERFLAVOR% c:\msys64\usr\bin\bash -l -c ^
+  "cd %CD:\=/% && ./bootstrap.sh --with-toolset=gcc" || EXIT /B
+
+c:\msys64\usr\bin\env MSYSTEM=%UPPERFLAVOR% c:\msys64\usr\bin\bash -l -c ^
+  "cd %CD:\=/% && ./b2 libs/%SELF% toolset=gcc-%FLAVOR% cxxstd=%CXXSTD% %CXXFLAGS% %DEFINES% %B2_ADDRESS_MODEL% %B2_LINK% %B2_THREADING% %B2_VARIANT% -j3" || EXIT /B
+
+EXIT /B 0
+
+::
+:: Function to uppercase a variable
+:: from: https://stackoverflow.com/questions/34713621/batch-converting-variable-to-uppercase
+::
+
+:TOUPPER <variable>
+@ECHO OFF
+FOR %%a IN ("a=A" "b=B" "c=C" "d=D" "e=E" "f=F" "g=G" "h=H" "i=I"
+            "j=J" "k=K" "l=L" "m=M" "n=N" "o=O" "p=P" "q=Q" "r=R"
+            "s=S" "t=T" "u=U" "v=V" "w=W" "x=X" "y=Y" "z=Z"      ) DO ( CALL SET %~1=%%%~1:%%~a%% )
+@ECHO ON
+GOTO :EOF

doc/Jamfile.v2

@@ -2,7 +2,22 @@
 import toolset ;
 toolset.using doxygen ;
 
-boostbook program_option : program_options.xml ;
+boostbook program_option 
+    : program_options.xml 
+    : <implicit-dependency>autodoc 
+      <xsl:param>boost.root=../../../..
+      <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html
+    ;
 
 doxygen autodoc 
-    : [ glob ../../../boost/program_options/*.hpp ] ;
+    : [ glob ../../../boost/program_options/*.hpp ] ;
+
+###############################################################################
+alias boostdoc
+    : program_options.xml
+    :
+    : <dependency>autodoc
+    : ;
+explicit boostdoc ;
+alias boostrelease ;
+explicit boostrelease ;

doc/design.xml

@@ -22,7 +22,7 @@
       not mean strict 7-bit ASCII encoding, but rather "char" strings in local
       8-bit encoding.
     </para>
-          
+
     <para>
       Generally, &quot;Unicode support&quot; can mean
       many things, but for the program_options library it means that:
@@ -52,10 +52,9 @@
               <listitem>
                 <para>ascii input passed to a Unicode value, and Unicode input
                   passed to an ascii value will be converted using a codecvt
-                  facet (which may be specified by the user(which can be
-                  specified by the user)
+                  facet (which may be specified by the user).
                 </para>
-              </listitem>                 
+              </listitem>
             </itemizedlist>
           </para>
         </listitem>
@@ -69,8 +68,8 @@
       Second, imagine a reusable library which has some options and exposes
       options description in its interface. If <emphasis>all</emphasis>
       options are either ascii or Unicode, and the library does not use any
-      Unicode strings, then the author will likely to use ascii options, which
-      would make the library unusable inside Unicode
+      Unicode strings, then the author is likely to use ascii options, making
+      the library unusable inside Unicode
       applications. Essentially, it would be necessary to provide two versions
       of the library -- ascii and Unicode.
     </para>
@@ -83,7 +82,7 @@
     </para>
 
     <para>The Unicode support outlined above is not complete. For example, we
-      don't plan allow Unicode in option names. Unicode support is hard and
+      don't support Unicode option names. Unicode support is hard and
       requires a Boost-wide solution. Even comparing two arbitrary Unicode
       strings is non-trivial. Finally, using Unicode in option names is
       related to internationalization, which has it's own
@@ -95,7 +94,7 @@
     <para>The primary question in implementing the Unicode support is whether
       to use templates and <code>std::basic_string</code> or to use some
       internal encoding and convert between internal and external encodings on
-      the interface boundaries.            
+      the interface boundaries.
     </para>
 
     <para>The choice, mostly, is between code size and execution
@@ -172,14 +171,14 @@
             number of new instantiations.
           </para>
         </listitem>
-          
+
       </itemizedlist>
       There's no clear leader, but the last point seems important, so UTF-8
-      will be used.      
+      will be used.
     </para>
 
-    <para>Choosing the UTF-8 encoding allows the use of existing parsers, 
-      because 7-bit ascii characters retain their values in UTF-8, 
+    <para>Choosing the UTF-8 encoding allows the use of existing parsers,
+      because 7-bit ascii characters retain their values in UTF-8,
       so searching for 7-bit strings is simple. However, there are
       two subtle issues:
       <itemizedlist>
@@ -198,16 +197,16 @@
       almost universal encoding and since composing characters following '=' (and
       other characters with special meaning to the library) are not likely to appear.
     </para>
-                   
+
   </section>
 
-  
+
 </section>
 
 <!--
      Local Variables:
      mode: xml
-     sgml-indent-data: t     
+     sgml-indent-data: t
      sgml-parent-document: ("program_options.xml" "section")
      sgml-set-face: t
      End:

doc/howto.xml

@@ -21,7 +21,7 @@ options groups/hidden options
 -->
   <section>
     <title>Non-conventional Syntax</title>
-    
+
     <para>Sometimes, standard command line syntaxes are not enough. For
     example, the gcc compiler has "-frtti" and -fno-rtti" options, and this
     syntax is not directly supported.
@@ -57,14 +57,14 @@ store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo)
         .run(), vm);
 </programlisting>
       The complete example can be found in the "example/custom_syntax.cpp"
-      file.                
+      file.
     </para>
   </section>
 
   <section>
     <title>Response Files</title>
 
-    <indexterm><primary>response files</primary></indexterm> 
+    <indexterm><primary>response files</primary></indexterm>
 
     <para>Some operating system have very low limits of the command line
       length. The common way to work around those limitations is using
@@ -79,7 +79,7 @@ store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo)
     <para>
       First, you need to define an option for the response file:
 <programlisting>
-("response-file", value&lt;string&gt;(), 
+("response-file", value&lt;string&gt;(),
      "can be specified with '@name', too")
 </programlisting>
     </para>
@@ -107,7 +107,7 @@ if (vm.count("response-file")) {
      // Load the file and tokenize it
      ifstream ifs(vm["response-file"].as<string>().c_str());
      if (!ifs) {
-         cout << "Could no open the response file\n";
+         cout << "Could not open the response file\n";
          return 1;
      }
      // Read the whole file into a string
@@ -115,18 +115,19 @@ if (vm.count("response-file")) {
      ss << ifs.rdbuf();
      // Split the file content
      char_separator<char> sep(" \n\r");
-     tokenizer<char_separator<char> > tok(ss.str(), sep);
+     std::string ResponsefileContents( ss.str() );
+     tokenizer<char_separator<char> > tok(ResponsefileContents, sep);
      vector<string> args;
      copy(tok.begin(), tok.end(), back_inserter(args));
      // Parse the file and store the options
-     store(command_line_parser(args).options(desc).run(), vm);     
+     store(command_line_parser(args).options(desc).run(), vm);
 }
 ]]>
 </programlisting>
       The complete example can be found in the "example/response_file.cpp"
-      file.                
+      file.
     </para>
- 
+
   </section>
 
   <section>
@@ -138,15 +139,15 @@ if (vm.count("response-file")) {
     compilers, it is possible to obtain
     the split command line, but it's not clear if all compilers support the
     same mechanism on all versions of the operating system. The
-    <code>split_command_line</code> function is a portable mechanism provided
+    <code>split_winmain</code> function is a portable mechanism provided
     by the library.</para>
 
     <para>Here's an example of use:
 <programlisting>
 vector&lt;string&gt; args = split_winmain(lpCmdLine);
 store(command_line_parser(args).options(desc).run(), vm);
-</programlisting>      
-      The function is an overload for <code>wchar_t</code> strings, so can
+</programlisting>
+      The <code>split_winmain</code> function is overloaded for <code>wchar_t</code> strings, so can
       also be used in Unicode applications.
     </para>
 
@@ -184,7 +185,7 @@ store(command_line_parser(args).options(desc).run(), vm);
 options_description general("General options");
 general.add_options()
     ("help", "produce a help message")
-    ("help-module", value<string>()->implicit(),
+    ("help-module", value<string>(),
         "produce a help for a given module")
     ("version", "output the version number")
     ;
@@ -222,7 +223,7 @@ visible.add(general).add(gui);
 variables_map vm;
 store(parse_command_line(ac, av, all), vm);
 
-if (vm.count("help")) 
+if (vm.count("help"))
 {
     cout << visible;
     return 0;
@@ -234,7 +235,7 @@ if (vm.count("help-module")) {
     } else if (s == "backend") {
         cout << backend;
     } else {
-        cout << "Unknown module '" 
+        cout << "Unknown module '"
              << s << "' in the --help-module option\n";
         return 1;
     }
@@ -242,8 +243,8 @@ if (vm.count("help-module")) {
 }
 if (vm.count("num-threads")) {
     cout << "The 'num-threads' options was set to "
-         << vm["num-threads"].as<int>() << "\n";            
-}                           
+         << vm["num-threads"].as<int>() << "\n";
+}
 ]]></programlisting>
       When parsing the command line, all options are allowed. The "--help"
       message, however, does not include the "Backend options" group -- the
@@ -252,7 +253,7 @@ if (vm.count("num-threads")) {
       option. The complete example can be found in the
       "example/option_groups.cpp" file.
     </para>
-  
+
   </section>
 
   <section>
@@ -275,7 +276,7 @@ public:
 };
 ]]></programlisting> and then overload the <code>validate</code> function:
 <programlisting><![CDATA[
-void validate(boost::any& v, 
+void validate(boost::any& v,
               const std::vector<std::string>& values,
               magic_number* target_type, int)
 {
@@ -284,21 +285,21 @@ void validate(boost::any& v,
     using namespace boost::program_options;
 
     // Make sure no previous assignment to 'a' was made.
-    validators::check_first_occurence(v);
+    validators::check_first_occurrence(v);
     // Extract the first string from 'values'. If there is more than
     // one string, it's an error, and exception will be thrown.
     const string& s = validators::get_single_string(values);
 
-    // Do regex match and convert the interesting part to 
+    // Do regex match and convert the interesting part to
     // int.
     smatch match;
     if (regex_match(s, match, r)) {
         v = any(magic_number(lexical_cast<int>(match[1])));
     } else {
-        throw validation_error("invalid value");
-    }        
+        throw validation_error(validation_error::invalid_option_value);
+    }
 }
-]]>        
+]]>
 </programlisting>The function takes four parameters. The first is the storage
       for the value, and in this case is either empty or contains an instance of
       the <code>magic_number</code> class. The second is the list of strings
@@ -371,7 +372,7 @@ void validate(boost::any& v,
 locale::global(locale(""));
       </programlisting>
       which would set up the conversion facet according to the user's selected
-      locale. 
+      locale.
     </para>
 
     <para>It's wise to check the status of the C++ locale support on your
@@ -381,7 +382,7 @@ locale::global(locale(""));
           <para>Go the the "test" directory and build the "test_convert" binary.</para>
         </listitem>
         <listitem>
-          <para>Set some non-ascii locale in the environmemt. On Linux, one can
+          <para>Set some non-ascii locale in the environment. On Linux, one can
           run, for example: <screen>
 $ export LC_CTYPE=ru_RU.KOI8-R
 </screen>
@@ -398,13 +399,101 @@ $ export LC_CTYPE=ru_RU.KOI8-R
 
     </section>
 
+    <section>
+      <title>Allowing Unknown Options</title>
+
+      <para>Usually, the library throws an exception on unknown option names. This
+      behaviour can be changed. For example, only some part of your application uses
+      <libraryname>Program_options</libraryname>, and you wish to pass unrecognized options to another part of
+      the program, or even to another application.</para>
+
+      <para>To allow unregistered options on the command line, you need to use
+      the &basic_command_line_parser; class for parsing (not &parse_command_line;)
+      and call the <methodname alt="boost::program_options::basic_command_line_parser::allow_unregistered">allow_unregistered</methodname>
+      method of that class:
+      <programlisting>
+parsed_options parsed =
+    command_line_parser(argc, argv).options(desc).allow_unregistered().run();
+      </programlisting>
+
+      For each token that looks like an option, but does not have a known name,
+      an instance of &basic_option; will be added to the result.
+      The <code>string_key</code> and <code>value</code> fields of the instance will contain results
+      of syntactic parsing of the token, the <code>unregistered</code> field will be set to <code>true</code>,
+      and the <code>original_tokens</code> field will contain the token as it appeared on the command line.
+      </para>
+
+      <para>If you want to pass the unrecognized options further, the
+      <functionname alt="boost::program_options::collect_unrecognized">collect_unrecognized</functionname> function can be used.
+      The function will collect original tokens for all unrecognized values, and optionally, all found positional options.
+      Say, if your code handles a few options, but does not handle positional options at all, you can use the function like this:
+      <programlisting>
+vector&lt;string&gt; to_pass_further = collect_unrecognized(parsed.options, include_positional);
+      </programlisting>
+
+      </para>
+
+    </section>
+
+    <section>
+      <title>Testing Option Presence</title>
+
+      <para>Until now we have tested whether an option has been set using the
+      <methodname alt="boost::program_options::variables_map::count">count</methodname> method on the &variables_map;
+      class; as you are repeating the (string literal) name of the option this is prone to typos and/or errors
+      resulting from renaming the option in one place but not the other:
+        <programlisting><![CDATA[
+po::options_description desc("Allowed options");
+desc.add_options()
+    ("compression", po::value<int>(), "set compression level")
+;
+
+po::variables_map vm;
+po::store(po::parse_command_line(ac, av, desc), vm);
+po::notify(vm);
+
+if (vm.count("compression")) {
+    cout << "Compression level was set to "
+ << vm["compression"].as<int>() << ".\n";
+} else {
+    cout << "Compression level was not set.\n";
+}
+]]>
+        </programlisting>
+      </para>
+
+      <para>Instead, you can use a variable of type <classname alt="boost::optional">boost::optional</classname>;
+      <libraryname>Program_options</libraryname> provides special support for <libraryname>Boost.Optional</libraryname>
+      such that if the user specifies the option the <classname alt="boost::optional">boost::optional</classname>
+      variable will be initialized to the appropriate value:
+        <programlisting><![CDATA[
+po::options_description desc("Allowed options");
+boost::optional<int> compression;
+desc.add_options()
+    ("compression", po::value(&compression), "set compression level")
+;
+
+po::variables_map vm;
+po::store(po::parse_command_line(ac, av, desc), vm);
+po::notify(vm);
+
+if (compression) {
+    cout << "Compression level was set to " << *compression << ".\n";
+} else {
+    cout << "Compression level was not set.\n";
+}
+]]>
+        </programlisting>
+      </para>
+    </section>
+
 </section>
 
 <!--
      Local Variables:
-     mode: xml
-     sgml-indent-data: t     
-     sgml-parent-document: ("program_options.xml" "section")
+     mode: nxml
+     sgml-indent-data: t
+     sgml-parent-document: ("userman.xml" "chapter")
      sgml-set-face: t
      End:
 -->

doc/index.html

@@ -1,9 +1,14 @@
 <html>
 <head>
-<meta http-equiv="refresh" content="0; URL=../../../doc/html/program_option.html">
+<meta http-equiv="refresh" content="0; URL=../../../doc/html/program_options.html">
 </head>
 <body>
 Automatic redirection failed, please go to
-<a href="../../../doc/html/program_options.html">../../../doc/html/program_options.html</a>
+<a href="../../../doc/html/program_options.html">../../../doc/html/program_options.html</a> 
+&nbsp;<hr>
+<p>© Copyright Beman Dawes, 2001</p>
+<p>Distributed under the Boost Software License, Version 1.0. (See accompanying 
+file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy 
+at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
 </body>
 </html>

doc/overview.xml

@@ -22,7 +22,7 @@
       </listitem>
       <listitem>
         <para>The parsers component, which uses this information to find option names
-          and values in the input sources and return them. 
+          and values in the input sources and return them.
         </para>
       </listitem>
       <listitem>
@@ -72,10 +72,10 @@
         </para>
       </listitem>
       <listitem>
-        <para>The storage component is focused on storing options values. It 
+        <para>The storage component is focused on storing options values. It
         </para>
       </listitem>
-  
+
 
     </itemizedlist>
 
@@ -105,7 +105,7 @@ desc.add_options()
     ("help", "produce help")
     ("optimization", value&lt;int&gt;()->default_value(10), "optimization level")
     ;
-</programlisting>      
+</programlisting>
     </para>
 
     <para>The call to the <code>value</code> function creates an instance of
@@ -116,14 +116,14 @@ desc.add_options()
       essentially emulates named parameters of the constructor.) Calls to
       <code>operator()</code> on the object returned by <code>add_options</code>
       forward arguments to the constructor of the <code>option_description</code>
-      class and add the new instance. 
+      class and add the new instance.
     </para>
 
     <para>
       Note that in addition to the
       <code>value</code>, library provides the <code>bool_switch</code>
       function, and user can write his own function which will return
-      other subclasses of <code>value_semantic</code> with 
+      other subclasses of <code>value_semantic</code> with
       different behaviour. For the remainder of this section, we'll talk only
       about the <code>value</code> function.
     </para>
@@ -135,7 +135,7 @@ desc.add_options()
       where value is just a vector of strings
       (<code>std::vector&lt;std::string&gt;</code>). The semantic layer
       is responsible for converting the value of the option into more usable C++
-      types. 
+      types.
     </para>
 
     <para>This separation is an important part of library design. The parsers
@@ -148,66 +148,173 @@ desc.add_options()
     </para>
 
     <section>
-      <title>Syntactic information</title>
+      <title>Syntactic Information</title>
       <para>The syntactic information is provided by the
         <classname>boost::program_options::options_description</classname> class
         and some methods of the
-        <classname>boost::program_options::value_semantic</classname> class.
-        The simplest usage is illustrated below:
-        <programlisting>
-          options_description desc;
-          desc.add_options()
-          ("help", "produce help message")
-          ;
-        </programlisting>
-        This declares one option named "help" and associates a description with
-        it. The user is not allowed to specify any value.
+        <classname>boost::program_options::value_semantic</classname> class
+        and includes:
+        <itemizedlist>
+          <listitem>
+            <para>
+              name of the option, used to identify the option inside the
+              program,
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              description of the option, which can be presented to the user,
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              the allowed number of source tokens that comprise options's
+              value, which is used during parsing.
+            </para>
+          </listitem>
+        </itemizedlist>
       </para>
-      
-      <para>To make an option accept a value, you'd need the
-        <code>value</code> function mentioned above:
+
+      <para>Consider the following example:
+      <programlisting>
+options_description desc;
+desc.add_options()
+    ("help", "produce help message")
+    ("compression", value&lt;string&gt;(), "compression level")
+    ("verbose", value&lt;string&gt;()->implicit_value("0"), "verbosity level")
+    ("email", value&lt;string&gt;()->multitoken(), "email to send to")
+    ;
+      </programlisting>
+      For the first parameter, we specify only the name and the
+      description. No value can be specified in the parsed source.
+      For the first option, the user must specify a value, using a single
+      token. For the third option, the user may either provide a single token
+      for the value, or no token at all. For the last option, the value can
+      span several tokens. For example, the following command line is OK:
+      <screen>
+          test --help --compression 10 --verbose --email beadle@mars beadle2@mars
+      </screen>
+      </para>
+
+      <section>
+        <title>Description formatting</title>
+
+        <para>
+          Sometimes the description can get rather long, for example, when
+          several option's values need separate documentation. Below we
+          describe some simple formatting mechanisms you can use.
+        </para>
+
+        <para>The description string has one or more paragraphs, separated by
+        the newline character ('\n'). When an option is output, the library
+        will compute the indentation for options's description. Each of the
+        paragraph is output as a separate line with that intentation. If
+        a paragraph does not fit on one line it is spanned over multiple
+        lines (which will have the same indentation).
+        </para>
+
+        <para>You may specify additional indent for the first specified by
+        inserting spaces at the beginning of a paragraph. For example:
         <programlisting>
-          options_description desc;
-          desc.add_options()
-          ("compression", "compression level", value&lt;string&gt;())
-          ("verbose", "verbosity level", value&lt;string&gt;()->implicit())
-          ("email", "email to send to", value&lt;string&gt;()->multitoken());
+options.add_options()
+    ("help", "   A long help msg a long help msg a long help msg a long help
+msg a long help msg a long help msg a long help msg a long help msg ")
+    ;
         </programlisting>
-        With these declarations, the user must specify a value for
-        the first option, using a single token. For the second option, the user
-        may either provide a single token for the value, or no token at
-        all. For the last option, the value can span several tokens. For
-        example, the following command line is OK:
+        will specify a four-space indent for the first line. The output will
+        look like:
         <screen>
-          test --compression 10 --verbose --email beadle@mars beadle2@mars
-        </screen>      
-      </para>
+  --help                    A long help msg a long
+                        help msg a long help msg
+                        a long help msg a long
+                        help msg a long help msg
+                        a long help msg a long
+                        help msg
+
+        </screen>
+        </para>
+
+        <para>For the case where line is wrapped, you can want an additional
+        indent for wrapped text. This can be done by
+        inserting a tabulator character ('\t') at the desired position. For
+        example:
+        <programlisting>
+options.add_options()
+      ("well_formated", "As you can see this is a very well formatted
+option description.\n"
+                        "You can do this for example:\n\n"
+                        "Values:\n"
+                        "  Value1: \tdoes this and that, bla bla bla bla
+bla bla bla bla bla bla bla bla bla bla bla\n"
+                        "  Value2: \tdoes something else, bla bla bla bla
+bla bla bla bla bla bla bla bla bla bla bla\n\n"
+                        "    This paragraph has a first line indent only,
+bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");
+        </programlisting>
+        will produce:
+        <screen>
+  --well_formated       As you can see this is a
+                        very well formatted
+                        option description.
+                        You can do this for
+                        example:
+
+                        Values:
+                          Value1: does this and
+                                  that, bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla
+                          Value2: does something
+                                  else, bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla bla bla bla
+                                  bla
+
+                            This paragraph has a
+                        first line indent only,
+                        bla bla bla bla bla bla
+                        bla bla bla bla bla bla
+                        bla bla bla
+        </screen>
+        The tab character is removed before output. Only one tabulator per
+        paragraph is allowed, otherwise an exception of type
+        program_options::error is thrown. Finally, the tabulator is ignored if
+        it is not on the first line of the paragraph or is on the last
+        possible position of the first line.
+        </para>
+
+      </section>
+
     </section>
-      
+
     <section>
-      <title>Semantic information</title>
-      
-      <para>The semantic information is completely provided by the 
+      <title>Semantic Information</title>
+
+      <para>The semantic information is completely provided by the
         <classname>boost::program_options::value_semantic</classname> class. For
         example:
 <programlisting>
 options_description desc;
 desc.add_options()
-    ("compression", "compression level", value&lt;int&gt;()->default(10));
-    ("email", "email", value&lt; vector&lt;string&gt; &gt;()
-        ->composing()->notify(&amp;your_function);
-</programlisting>      
+    ("compression", value&lt;int&gt;()->default_value(10), "compression level")
+    ("email", value&lt; vector&lt;string&gt; &gt;()
+        ->composing()->notifier(&amp;your_function), "email")
+    ;
+</programlisting>
         These declarations specify that default value of the first option is 10,
         that the second option can appear several times and all instances should
         be merged, and that after parsing is done, the library will  call
         function <code>&amp;your_function</code>, passing the value of the
-        "email" option as argument.      
+        "email" option as argument.
       </para>
     </section>
-    
+
     <section>
-      <title>Positional options</title>
-      
+      <title>Positional Options</title>
+
       <para>Our definition of option as (name, value) pairs is simple and
         useful, but in one special case of the command line, there's a
         problem. A command line can include a <firstterm>positional option</firstterm>,
@@ -217,7 +324,7 @@ desc.add_options()
         </screen>
         Here, the "/etc/passwd" element does not have any option name.
       </para>
-      
+
       <para>One solution is to ask the user to extract positional options
         himself and process them as he likes. However, there's a nicer approach
         -- provide a method to automatically assign the names for positional
@@ -227,30 +334,37 @@ desc.add_options()
           archiver --compression=9 --input-file=/etc/passwd
         </screen>
       </para>
-      
+
       <para>The &positional_options_desc; class allows the command line
         parser to assign the names. The class specifies how many positional options
         are allowed, and for each allowed option, specifies the name. For example:
-        <programlisting>
-          positional_options_description pd; pd.add("input-file", 1, 1);
-        </programlisting> specifies that for exactly one, first, positional
+<programlisting>
+positional_options_description pd; pd.add("input-file", 1);
+</programlisting> specifies that for exactly one, first, positional
         option the name will be "input-file".
       </para>
-      
+
       <para>It's possible to specify that a number, or even all positional options, be
         given the same name.
-        <programlisting>
-          positional_options_description pd;
-          pd.add("output-file", 2, 2).add_optional("input-file", 0, -1);
-        </programlisting>
+<programlisting>
+positional_options_description pd;
+pd.add("output-file", 2).add("input-file", -1);
+</programlisting>
         In the above example, the first two positional options will be associated
         with name "output-file", and any others with the name "input-file".
       </para>
-      
+
+    <warning>
+      <para>The &positional_options_desc; class only specifies translation from
+      position to name, and the option name should still be registered with
+      an instance of the &options_description; class.</para>
+    </warning>
+
+
     </section>
-              
+
     <!-- Note that the classes are not modified during parsing -->
-          
+
   </section>
 
   <section>
@@ -276,7 +390,7 @@ desc.add_options()
       The results of parsing are returned as an instance of the &parsed_options;
       class. Typically, that object is passed directly to the storage
       component. However, it also can be used directly, or undergo some additional
-      processing. 
+      processing.
     </para>
 
     <para>
@@ -308,8 +422,8 @@ desc.add_options()
           </para>
         </listitem>
       </itemizedlist>
-    </para>      
-    
+    </para>
+
   </section>
 
 
@@ -334,12 +448,12 @@ desc.add_options()
     </para>
 
     <para>Let's consider an example:
-      <programlisting>
-        variables_map vm;
-        store(parse_command_line(argc, argv, desc), vm);
-        store(parse_config_file("example.cfg", desc), vm);
-        notify(vm);
-      </programlisting>
+<programlisting>
+variables_map vm;
+store(parse_command_line(argc, argv, desc), vm);
+store(parse_config_file("example.cfg", desc), vm);
+notify(vm);
+</programlisting>
       The <code>variables_map</code> class is used to store the option
       values. The two calls to the <code>store</code> function add values
       found on the command line and in the config file. Finally the call to
@@ -360,31 +474,165 @@ desc.add_options()
 
   </section>
 
+  <section>
+    <title>Specific parsers</title>
+
+    <section>
+      <title>Configuration file parser</title>
+
+      <para>The &parse_config_file; function implements parsing
+      of simple INI-like configuration files. Configuration file
+      syntax is line based:
+      </para>
+      <itemizedlist>
+        <listitem><para>A line in the form:</para>
+        <screen>
+<replaceable>name</replaceable>=<replaceable>value</replaceable>
+        </screen>
+        <para>gives a value to an option.</para>
+        </listitem>
+        <listitem><para>A line in the form:</para>
+        <screen>
+[<replaceable>section name</replaceable>]
+        </screen>
+        <para>introduces a new section in the configuration file.</para>
+        </listitem>
+        <listitem><para>The <literal>#</literal> character introduces a
+        comment that spans until the end of the line.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>The option names are relative to the section names, so
+      the following configuration file part:</para>
+      <screen>
+[gui.accessibility]
+visual_bell=yes
+      </screen>
+      <para>is equivalent to</para>
+      <screen>
+gui.accessibility.visual_bell=yes
+      </screen>
+      <para>When the option "gui.accessibility.visual_bell" has been added to the options</para>
+      <programlisting>
+options_description desc;
+desc.add_options()
+    ("gui.accessibility.visual_bell", value&lt;string&gt;(), "flash screen for bell")
+    ;
+    </programlisting>
+    </section>
+
+    <section>
+      <title>Environment variables parser</title>
+
+      <para><firstterm>Environment variables</firstterm> are string variables
+      which are available to all programs via the <code>getenv</code> function
+      of C runtime library. The operating system allows to set initial values
+      for a given user, and the values can be further changed on the command
+      line.  For example, on Windows one can use the
+      <filename>autoexec.bat</filename> file or (on recent versions) the
+      <filename>Control Panel/System/Advanced/Environment Variables</filename>
+      dialog, and on Unix &#x2014;, the <filename>/etc/profile</filename>,
+      <filename>~/.profile</filename> and <filename>~/.bash_profile</filename>
+      files. Because environment variables can be set for the entire system,
+      they are particularly suitable for options which apply to all programs.
+      </para>
+
+      <para>The environment variables can be parsed with the
+      &parse_environment; function. The function have several overloaded
+      versions. The first parameter is always an &options_description;
+      instance, and the second specifies what variables must be processed, and
+      what option names must correspond to it. To describe the second
+      parameter we need to consider naming conventions for environment
+      variables.</para>
+
+      <para>If you have an option that should be specified via environment
+      variable, you need make up the variable's name. To avoid name clashes,
+      we suggest that you use a sufficiently unique prefix for environment
+      variables. Also, while option names are most likely in lower case,
+      environment variables conventionally use upper case. So, for an option
+      name <literal>proxy</literal> the environment variable might be called
+      <envar>BOOST_PROXY</envar>. During parsing, we need to perform reverse
+      conversion of the names. This is accomplished by passing the choosen
+      prefix as the second parameter of the &parse_environment; function.
+      Say, if you pass <literal>BOOST_</literal> as the prefix, and there are
+      two variables, <envar>CVSROOT</envar> and <envar>BOOST_PROXY</envar>, the
+      first variable will be ignored, and the second one will be converted to
+      option <literal>proxy</literal>.
+      </para>
+
+      <para>The above logic is sufficient in many cases, but it is also
+      possible to pass, as the second parameter of the &parse_environment;
+      function, any function taking a <code>std::string</code> and returning
+      <code>std::string</code>. That function will be called for each
+      environment variable and should return either the name of the option, or
+      empty string if the variable should be ignored. An example showing this
+      method can be found in "example/env_options.cpp".
+      </para>
+
+    </section>
+  </section>
+
+  <section>
+    <title>Types</title>
+
+    <para>Everything that is passed in on the command line, as an environmental
+    variable, or in a config file is a string. For values that need to be used
+    as a non-string type, the value in the variables_map will attempt to 
+    convert it to the correct type.</para>
+
+    <para>Integers and floating point values are converted using Boost's 
+    lexical_cast. It will accept integer values such as "41" or "-42". It will
+    accept floating point numbers such as "51.1", "-52.1", "53.1234567890" (as
+    a double), "54", "55.", ".56", "57.1e5", "58.1E5", ".591e5", "60.1e-5", 
+    "-61.1e5", "-62.1e-5", etc. Unfortunately, hex, octal, and binary
+    representations that are available in C++ literals are not supported by
+    lexical_cast, and thus will not work with program_options.</para>
+
+    <para>Booleans a special in that there are multiple ways to come at them. 
+    Similar to another value type, it can be specified as <code>("my-option",
+    value&lt;bool&gt;())</code>, and then set as:</para>
+    <screen>
+example --my-option=true
+    </screen>
+    <para>However, more typical is that boolean values are set by the simple
+    presence of a switch. This is enabled by &bool_switch; as in <code>
+    ("other-option", bool_switch())</code>. This will cause the value to
+    default to false and it will become true if the switch is found:</para>
+    <screen>
+example --other-switch
+    </screen>
+    <para>When a boolean does take a parameter, there are several options. 
+    Those that evaluate to true in C++ are: "true", "yes", "on", "1". Those
+    that evaluate to false in C++ are: "false", "no", "off", "0". In addition,
+    when reading from a config file, the option name with an equal sign and no
+    value after it will also evaluate to true.</para>
+  </section>
+
   <section>
     <title>Annotated List of Symbols</title>
-    
+
     <para>The following table describes all the important symbols in the
       library, for quick access.</para>
-    
+
     <informaltable pgwide="1">
-        
+
       <tgroup cols="2">
         <colspec colname='c1'/>
         <colspec colname='c2'/>
         <thead>
-          
-          <row>            
+
+          <row>
             <entry>Symbol</entry>
             <entry>Description</entry>
           </row>
         </thead>
-        
+
         <tbody>
-          
-          <row>            
+
+          <row>
             <entry namest='c1' nameend='c2'>Options description component</entry>
           </row>
-          
+
           <row>
             <entry>&options_description;</entry>
             <entry>describes a number of options</entry>
@@ -394,14 +642,21 @@ desc.add_options()
             <entry>defines the option's value</entry>
           </row>
 
-          <row>            
+          <row>
             <entry namest='c1' nameend='c2'>Parsers component</entry>
           </row>
-          
+
           <row>
             <entry>&parse_command_line;</entry>
-            <entry>parses command line</entry>
+            <entry>parses command line (simpified interface)</entry>
           </row>
+
+          <row>
+            <entry>&basic_command_line_parser;</entry>
+            <entry>parses command line (extended interface)</entry>
+          </row>
+
+
           <row>
             <entry>&parse_config_file;</entry>
             <entry>parses config file</entry>
@@ -412,7 +667,7 @@ desc.add_options()
             <entry>parses environment</entry>
           </row>
 
-          <row>            
+          <row>
             <entry namest='c1' nameend='c2'>Storage component</entry>
           </row>
 
@@ -420,21 +675,21 @@ desc.add_options()
             <entry>&variables_map;</entry>
             <entry>storage for option values</entry>
           </row>
-   
+
         </tbody>
       </tgroup>
-      
+
     </informaltable>
-    
+
   </section>
-  
+
 </section>
 
 <!--
      Local Variables:
-     mode: xml
-     sgml-indent-data: t     
+     mode: nxml
+     sgml-indent-data: t
      sgml-parent-document: ("program_options.xml" "section")
      sgml-set-face: t
      End:
--->
+-->

doc/post_review_plan.txt

@@ -151,7 +151,7 @@
    - test additional parser
    - Show default values in help output
    - Adaptive field width
-   - Mandatory options
+   - Mandatory options (2 votes (second Jonathan Graehl))
    - (new) return vector from parsers by auto_ptr, not by value?
    - (new) rename value_semantic into value_description
    - (new) output for positional_options_description
@@ -178,5 +178,4 @@
         
 12. Deferred 
 
-   - storing value to boost::optional 
    - setting a flag when option is found 

doc/program_options.ent

@@ -37,3 +37,12 @@
 <!ENTITY command_line_parser
      "<classname alt='boost::program_options::command_line_parser'>command_line_parser</classname>">
 
+<!ENTITY basic_command_line_parser
+     "<classname alt='boost::program_options::basic_command_line_parser'>basic_command_line_parser</classname>">
+
+
+<!ENTITY basic_option
+     "<classname alt='boost::program_options::basic_option'>basic_option</classname>">
+
+<!ENTITY bool_switch
+     "<functionname alt='boost::program_options::bool_switch'>bool_switch</functionname>">

doc/program_options.xml

@@ -83,5 +83,5 @@
   <xi:include href="design.xml"/>
   <xi:include href="acknowledgements.xml"/>    
    
-  <xi:include href="autodoc.boostbook"/> 
+  <xi:include href="autodoc.xml"/> 
 </library>

doc/rationale

@@ -4,12 +4,12 @@ implement generic composition classes. The former was choosen,
 mostly because of simplicity.
 
 There were two implementation approaches for multiple option
-occurences in options_and_arguments. First is store them
+occurrences in options_and_arguments. First is store them
 separately. The advantage is that it's easy to obtain all
-occurences before certain position on command line. The
+occurrences before certain position on command line. The
 disadvantage is that we cannot return a reference to 
 vector<vector<string> > in get_all_values. It was considered
 that if support for position-dependent options is to be
-added, then we're be mostly interested in occurences of 
+added, then we're be mostly interested in occurrences of
 a single option that were before some point. That's possible
-with vector<vector<string> > storage.
+with vector<vector<string> > storage.

doc/rationale.dox

@@ -81,7 +81,7 @@
 
     @section help_handling Handling of --help
 
-    It was suggested by Gennadiy Rozental that occurence of <tt>--help</tt>
+    It was suggested by Gennadiy Rozental that occurrence of <tt>--help</tt>
     on command line results in throwing an exception. Actually, the 
     &quot;special&quot; option must have been configurable. This was not 
     implemented, because applications might reasonable want to process

doc/todo.txt

@@ -1,4 +1,20 @@
 
+Say that variables_map is actually derived from std::map.
+
+Make parse_config_file("foo.cfg", desc) work.
+
+Document handling of positional options which depends on precedding options. 
+I.e scanning the parsed options and creating new variables_map when we see
+a positional option. (Email from Tony).
+
+> My instinctive reaction is to provide both via an options argument to
+> split_command_line (a name that would now be more appropriate). But I
+> haven't devoted much time to thinking this through, so I may be wrong. :-)
+> 
+> In any event, the tokenization isn't much fun. I'd expect the library to
+> provide a convenient mechanism for parsing a response file.
+
+
 > Similarly, is there some easy to use hook for customizing the "arg" to
 > indicate the type of the data (similar to how the textual representation
 > of the default argument can be changed, e.g.
@@ -201,3 +217,22 @@ More visibility for bool_switch.
 > as what can be achieved with the po::command_line_style::style_t enum. I
 > think most users will need this information sooner or later. A few
 > examples would be fine... But then again time is such a precious thing
+
+> Does the library supports sections in config files
+
+> What about the combination of (if some user-settable switch is thrown,
+> but not by default):
+> 
+> * allowing unknown options -- these are considered positional parameters
+> * rearranging the argument list such that all positional parameters
+> are moved to the end
+> 
+> This way:
+> 
+> program --unknown 42 --known-flag --known-arg value
+> 
+> is handled as if it were (in standard UNIX command-line-ese):
+> 
+> program --known-flag --known-arg value -- --unknown 42
+
+

doc/tutorial.xml

@@ -77,14 +77,13 @@ if (vm.count("compression")) {
   <para>It's now a good time to try compiling the code yourself, but if
     you're not yet ready, here's an example session:
 <screen>
-$bin/gcc/debug/first
+$ <userinput>bin/gcc/debug/first</userinput>
 Compression level was not set.
-$bin/gcc/debug/first --help
+$ <userinput>bin/gcc/debug/first --help</userinput>
 Allowed options:
   --help                 : produce help message
   --compression arg      : set compression level
-
-$bin/gcc/debug/first --compression 10
+$ <userinput>bin/gcc/debug/first --compression 10</userinput>
 Compression level was set to 10.
     </screen>
   </para>
@@ -97,7 +96,7 @@ Compression level was set to 10.
   <para>An option value, surely, can have other types than <code>int</code>, and
   can have other interesting properties, which we'll discuss right now. The
   complete version of the code snipped below can be found in
-  "example/options_description.cpp".</para>
+  <filename>example/options_description.cpp</filename>.</para>
 
   <para>Imagine we're writing a compiler. It should take the optimization
     level, a number of include paths, and a number of input files, and perform some
@@ -116,30 +115,38 @@ desc.add_options()
 </programlisting>
   </para>
 
-  <para>The "--help" option should be familiar from the previous example. 
-    It's a good idea to have this option in all cases.</para>
+  <para>The <literal>"help"</literal> option should be familiar from 
+  the previous example. It's a good idea to have this option in all cases.
+  </para>
 
-  <para>The "optimization" option shows two new features. First, we specify
+  <para>The <literal>"optimization"</literal> option shows two new features. First, we specify
     the address of the variable(<code>&amp;opt</code>). After storing values, that
     variable will have the value of the option. Second, we specify a default
     value of 10, which will be used if no value is specified by the user.
   </para>
 
-  <para>The "include-path" option is an example of the only case where
-    the interface of the <code>options_description</code> class serves only one
+  <para>The <literal>"include-path"</literal> option is an example of the 
+  only case where the interface of the <code>options_description</code> 
+  class serves only one
     source -- the command line. Users typically like to use short option names
     for common options, and the "include-path,I" name specifies that short
     option name is "I". So, both "--include-path" and "-I" can be used.
   </para>
+
+  <para>Note also that the type of the <literal>"include-path"</literal>
+  option is <type>std::vector</type>. The library provides special 
+  support for vectors -- it will be possible to specify the option several 
+  times, and all specified values will be collected in one vector.  
+  </para>
     
   <para>The "input-file" option specifies the list of files to
     process. That's okay for a start, but, of course, writing something like:
     <screen>
-compiler --input-file=a.cpp
+<userinput>compiler --input-file=a.cpp</userinput>
     </screen>
     is a little non-standard, compared with
     <screen>
-compiler a.cpp
+<userinput>compiler a.cpp</userinput>
     </screen>
     We'll address this in a moment.
   </para>
@@ -192,18 +199,18 @@ cout &lt;&lt; &quot;Optimization level is &quot; &lt;&lt; opt &lt;&lt; &quot;\n&
 
   <para>Here's an example session:
     <screen>
-$bin/gcc/debug/options_description --help
+$ <userinput>bin/gcc/debug/options_description --help</userinput>
 Usage: options_description [options]
 Allowed options:
   --help                 : produce help message
   --optimization arg     : optimization level
   -I [ --include-path ] arg : include path
   --input-file arg       : input file
-$bin/gcc/debug/options_description
+$ <userinput>bin/gcc/debug/options_description</userinput>
 Optimization level is 10
-$bin/gcc/debug/options_description --optimization 4 -I foo a.cpp
-Include paths are: foo
-Input files are: a.cpp
+$ <userinput>bin/gcc/debug/options_description --optimization 4 -I foo -I another/path --include-path third/include/path a.cpp b.cpp</userinput>
+Include paths are: foo another/path third/include/path
+Input files are: a.cpp b.cpp
 Optimization level is 4
 </screen>
   </para>
@@ -301,10 +308,10 @@ visible.add(generic).add(config);
 
     <para>Here's an example session:
 <screen>
-$bin/gcc/debug/multiple_sources
+$ <userinput>bin/gcc/debug/multiple_sources</userinput>
 Include paths are: /opt
 Optimization level is 1
-$bin/gcc/debug/multiple_sources --help
+$ <userinput>bin/gcc/debug/multiple_sources --help</userinput>
 Allows options:
 
 Generic options:
@@ -315,7 +322,7 @@ Configuration:
   --optimization n       : optimization level
   -I [ --include-path ] path : include path
 
-$bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp
+$ <userinput>bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp</userinput>
 Include paths are: foo /opt
 Input files are: a.cpp b.cpp
 Optimization level is 4
@@ -338,9 +345,9 @@ Optimization level is 4
 
 <!--
      Local Variables:
-     mode: xml
+     mode: nxml
      sgml-indent-data: t     
      sgml-parent-document: ("program_options.xml" "section")
      sgml-set-face: t
      End:
--->
+-->

example/Jamfile

@@ -1,23 +0,0 @@
-
-subproject libs/program_options/example ;
-
-rule program-options-example ( name extra-sources * )
-{
-    exe $(name) : $(name).cpp <lib>../build/boost_program_options $(extra-sources)
-    : <include>$(BOOST_ROOT) ;
-}
-
-program-options-example first ;
-program-options-example options_description ;
-program-options-example multiple_sources ;
-program-options-example custom_syntax ;
-program-options-example response_file ;
-program-options-example option_groups ;
-program-options-example real ;
-program-options-example regex <lib>../../regex/build/boost_regex ;
-
-
-#program-options-example prefix ;
-
-
-

example/Jamfile.v2

@@ -1,7 +1,8 @@
 
 project 
-    : requirements <library>../build//program_options
+    : requirements <library>../build//boost_program_options
       <hardcode-dll-paths>true
+      <link>static
     ;
 
 exe first : first.cpp ;
@@ -9,7 +10,12 @@ exe options_description : options_description.cpp ;
 exe multiple_sources : multiple_sources.cpp ;
 exe custom_syntax : custom_syntax.cpp ;
 
-exe a : a.cpp ;
+exe real : real.cpp ;
+exe regex : regex.cpp /boost/regex//boost_regex ;
 
-#exe real : real.cpp ;
-#exe regex : regex.cpp /boost/regex//boost_regex ;
+# The following examples use C++ features beyond C++03.
+# It would be possible to make compilation of each conditional on specific config check,
+# for now just disable the compilation.
+#exe config_file_types : config_file_types.cpp ;
+#exe env_options : env_options.cpp ;
+#exe options_heirarchy : options_heirarchy.cpp ;

example/config_file_types.cpp

@@ -0,0 +1,242 @@
+// Copyright Thomas Kent 2016
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+// This example shows a config file (in ini format) being parsed by the
+// program_options library. It includes a numebr of different value types.
+
+#include <boost/program_options.hpp>
+namespace po = boost::program_options;
+
+#include <assert.h>
+#include <iostream>
+#include <sstream>
+using namespace std;
+
+const double FLOAT_SEPERATION = 0.00000000001;
+bool check_float(double test, double expected)
+{
+   double seperation = expected * (1 + FLOAT_SEPERATION) / expected;
+   if ((test < expected + seperation) && (test > expected - seperation))
+   {
+      return true;
+   }
+   return false;
+}
+
+stringstream make_file()
+{
+   stringstream ss;
+   ss << "# This file checks parsing of various types of config values\n";
+   //FAILS: ss << "; a windows style comment\n";
+
+   ss << "global_string = global value\n";
+   ss << "unregistered_entry = unregistered value\n";
+
+   ss << "\n[strings]\n";
+   ss << "word = word\n";
+   ss << "phrase = this is a phrase\n";
+   ss << "quoted = \"quotes are in result\"\n";
+   
+   ss << "\n[ints]\n";
+   ss << "positive = 41\n";
+   ss << "negative = -42\n";
+   //FAILS: Lexical cast doesn't support hex, oct, or bin
+   //ss << "hex = 0x43\n";
+   //ss << "oct = 044\n";
+   //ss << "bin = 0b101010\n";
+
+   ss << "\n[floats]\n";
+   ss << "positive = 51.1\n";
+   ss << "negative = -52.1\n";
+   ss << "double = 53.1234567890\n";
+   ss << "int = 54\n";
+   ss << "int_dot = 55.\n";
+   ss << "dot = .56\n";
+   ss << "exp_lower = 57.1e5\n";
+   ss << "exp_upper = 58.1E5\n";
+   ss << "exp_decimal = .591e5\n";
+   ss << "exp_negative = 60.1e-5\n";
+   ss << "exp_negative_val = -61.1e5\n";
+   ss << "exp_negative_negative_val = -62.1e-5\n";
+
+   ss << "\n[booleans]\n";
+   ss << "number_true = 1\n";
+   ss << "number_false = 0\n";
+   ss << "yn_true = yes\n";
+   ss << "yn_false = no\n";
+   ss << "tf_true = true\n";
+   ss << "tf_false = false\n";
+   ss << "onoff_true = on\n";
+   ss << "onoff_false = off\n";
+   ss << "present_equal_true = \n";
+   //FAILS: Must be an = 
+   //ss << "present_no_equal_true\n";
+
+   ss.seekp(ios_base::beg);
+   return ss;
+}
+
+po::options_description set_options()
+{
+   po::options_description opts;
+   opts.add_options()
+      ("global_string", po::value<string>())
+
+      ("strings.word", po::value<string>())
+      ("strings.phrase", po::value<string>())
+      ("strings.quoted", po::value<string>())
+
+      ("ints.positive", po::value<int>())
+      ("ints.negative", po::value<int>())
+      ("ints.hex", po::value<int>())
+      ("ints.oct", po::value<int>())
+      ("ints.bin", po::value<int>())
+
+      ("floats.positive", po::value<float>())
+      ("floats.negative", po::value<float>())
+      ("floats.double", po::value<double>())
+      ("floats.int", po::value<float>())
+      ("floats.int_dot", po::value<float>())
+      ("floats.dot", po::value<float>())
+      ("floats.exp_lower", po::value<float>())
+      ("floats.exp_upper", po::value<float>())
+      ("floats.exp_decimal", po::value<float>())
+      ("floats.exp_negative", po::value<float>())
+      ("floats.exp_negative_val", po::value<float>())
+      ("floats.exp_negative_negative_val", po::value<float>())
+
+      // Load booleans as value<bool>, so they will require a --option=value on the command line
+      //("booleans.number_true", po::value<bool>())
+      //("booleans.number_false", po::value<bool>())
+      //("booleans.yn_true", po::value<bool>())
+      //("booleans.yn_false", po::value<bool>())
+      //("booleans.tf_true", po::value<bool>())
+      //("booleans.tf_false", po::value<bool>())
+      //("booleans.onoff_true", po::value<bool>())
+      //("booleans.onoff_false", po::value<bool>())
+      //("booleans.present_equal_true", po::value<bool>())
+      //("booleans.present_no_equal_true", po::value<bool>())
+
+      // Load booleans as bool_switch, so that a --option will set it true on the command line
+      // The difference between these two types does not show up when parsing a file
+      ("booleans.number_true", po::bool_switch())
+      ("booleans.number_false", po::bool_switch())
+      ("booleans.yn_true", po::bool_switch())
+      ("booleans.yn_false", po::bool_switch())
+      ("booleans.tf_true", po::bool_switch())
+      ("booleans.tf_false", po::bool_switch())
+      ("booleans.onoff_true", po::bool_switch())
+      ("booleans.onoff_false", po::bool_switch())
+      ("booleans.present_equal_true", po::bool_switch())
+      ("booleans.present_no_equal_true", po::bool_switch())
+      ;
+   return opts;
+}
+
+vector<string> parse_file(stringstream &file, po::options_description &opts, po::variables_map &vm)
+{
+   const bool ALLOW_UNREGISTERED = true;
+   cout << file.str() << endl;
+
+   po::parsed_options parsed = parse_config_file(file, opts, ALLOW_UNREGISTERED);
+   store(parsed, vm);
+   vector<string> unregistered = po::collect_unrecognized(parsed.options, po::exclude_positional);
+   notify(vm);
+
+   return unregistered;
+}
+
+void check_results(po::variables_map &vm, vector<string> unregistered)
+{
+   // Check that we got the correct values back
+   string expected_global_string = "global value";
+
+   string expected_unreg_option = "unregistered_entry";
+   string expected_unreg_value = "unregistered value";
+
+   string expected_strings_word = "word";
+   string expected_strings_phrase = "this is a phrase";
+   string expected_strings_quoted = "\"quotes are in result\"";
+
+   int expected_int_postitive = 41;
+   int expected_int_negative = -42;
+   int expected_int_hex = 0x43;
+   int expected_int_oct = 044;
+   int expected_int_bin = 0b101010;
+
+   float expected_float_positive = 51.1f;
+   float expected_float_negative = -52.1f;
+   double expected_float_double = 53.1234567890;
+   float expected_float_int = 54.0f;
+   float expected_float_int_dot = 55.0f;
+   float expected_float_dot = .56f;
+   float expected_float_exp_lower = 57.1e5f;
+   float expected_float_exp_upper = 58.1E5f;
+   float expected_float_exp_decimal = .591e5f;
+   float expected_float_exp_negative = 60.1e-5f;
+   float expected_float_exp_negative_val = -61.1e5f;
+   float expected_float_exp_negative_negative_val = -62.1e-5f;
+
+   bool expected_number_true = true;
+   bool expected_number_false = false;
+   bool expected_yn_true = true;
+   bool expected_yn_false = false;
+   bool expected_tf_true = true;
+   bool expected_tf_false = false;
+   bool expected_onoff_true = true;
+   bool expected_onoff_false = false;
+   bool expected_present_equal_true = true;
+   bool expected_present_no_equal_true = true;
+
+   assert(vm["global_string"].as<string>() == expected_global_string);
+
+   assert(unregistered[0] == expected_unreg_option);
+   assert(unregistered[1] == expected_unreg_value);
+
+   assert(vm["strings.word"].as<string>() == expected_strings_word);
+   assert(vm["strings.phrase"].as<string>() == expected_strings_phrase);
+   assert(vm["strings.quoted"].as<string>() == expected_strings_quoted);
+
+   assert(vm["ints.positive"].as<int>() == expected_int_postitive);
+   assert(vm["ints.negative"].as<int>() == expected_int_negative);
+   //assert(vm["ints.hex"].as<int>() == expected_int_hex);
+   //assert(vm["ints.oct"].as<int>() == expected_int_oct);
+   //assert(vm["ints.bin"].as<int>() == expected_int_bin);
+
+   assert(check_float(vm["floats.positive"].as<float>(), expected_float_positive));
+   assert(check_float(vm["floats.negative"].as<float>(), expected_float_negative));
+   assert(check_float(vm["floats.double"].as<double>(), expected_float_double));
+   assert(check_float(vm["floats.int"].as<float>(), expected_float_int));
+   assert(check_float(vm["floats.int_dot"].as<float>(), expected_float_int_dot));
+   assert(check_float(vm["floats.dot"].as<float>(), expected_float_dot));
+   assert(check_float(vm["floats.exp_lower"].as<float>(), expected_float_exp_lower));
+   assert(check_float(vm["floats.exp_upper"].as<float>(), expected_float_exp_upper));
+   assert(check_float(vm["floats.exp_decimal"].as<float>(), expected_float_exp_decimal));
+   assert(check_float(vm["floats.exp_negative"].as<float>(), expected_float_exp_negative));
+   assert(check_float(vm["floats.exp_negative_val"].as<float>(), expected_float_exp_negative_val));
+   assert(check_float(vm["floats.exp_negative_negative_val"].as<float>(), expected_float_exp_negative_negative_val));
+
+   assert(vm["booleans.number_true"].as<bool>() == expected_number_true);
+   assert(vm["booleans.number_false"].as<bool>() == expected_number_false);
+   assert(vm["booleans.yn_true"].as<bool>() == expected_yn_true);
+   assert(vm["booleans.yn_false"].as<bool>() == expected_yn_false);
+   assert(vm["booleans.tf_true"].as<bool>() == expected_tf_true);
+   assert(vm["booleans.tf_false"].as<bool>() == expected_tf_false);
+   assert(vm["booleans.onoff_true"].as<bool>() == expected_onoff_true);
+   assert(vm["booleans.onoff_false"].as<bool>() == expected_onoff_false);
+   assert(vm["booleans.present_equal_true"].as<bool>() == expected_present_equal_true);
+   //assert(vm["booleans.present_no_equal_true"].as<bool>() == expected_present_no_equal_true);
+}
+
+int main(int ac, char* av[])
+{
+   auto file = make_file();
+   auto opts = set_options();
+   po::variables_map vars;
+   auto unregistered = parse_file(file, opts, vars);
+   check_results(vars, unregistered);   
+
+   return 0;
+}

example/env_options.cpp

@@ -0,0 +1,47 @@
+// Copyright Thomas Kent 2016
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#include <boost/program_options.hpp>
+namespace po = boost::program_options;
+#include <string>
+#include <iostream>
+
+std::string mapper(std::string env_var)
+{
+   // ensure the env_var is all caps
+   std::transform(env_var.begin(), env_var.end(), env_var.begin(), ::toupper);
+
+   if (env_var == "PATH") return "path";
+   if (env_var == "EXAMPLE_VERBOSE") return "verbosity";
+   return "";
+}
+
+void get_env_options()
+{
+   po::options_description config("Configuration");
+   config.add_options()
+      ("path", "the execution path")
+      ("verbosity", po::value<std::string>()->default_value("INFO"), "set verbosity: DEBUG, INFO, WARN, ERROR, FATAL")
+      ;
+
+   po::variables_map vm;
+   store(po::parse_environment(config, boost::function1<std::string, std::string>(mapper)), vm);
+   notify(vm);
+
+   if (vm.count("path"))
+   {
+      std::cout << "First 75 chars of the system path: \n";
+      std::cout << vm["path"].as<std::string>().substr(0, 75) << std::endl;
+   }
+
+   std::cout << "Verbosity: " << vm["verbosity"].as<std::string>() << std::endl;
+}
+
+int main(int ac, char* av[])
+{
+   get_env_options();
+
+   return 0;
+}

example/first.cpp

@@ -20,7 +20,7 @@ int main(int ac, char* av[])
         po::options_description desc("Allowed options");
         desc.add_options()
             ("help", "produce help message")
-            ("compression", po::value<int>(), "set compression level")
+            ("compression", po::value<double>(), "set compression level")
         ;
 
         po::variables_map vm;        
@@ -29,12 +29,12 @@ int main(int ac, char* av[])
 
         if (vm.count("help")) {
             cout << desc << "\n";
-            return 1;
+            return 0;
         }
 
         if (vm.count("compression")) {
             cout << "Compression level was set to " 
-                 << vm["compression"].as<int>() << ".\n";
+                 << vm["compression"].as<double>() << ".\n";
         } else {
             cout << "Compression level was not set.\n";
         }

example/multiple_sources.cpp

@@ -18,7 +18,7 @@ using namespace std;
 template<class T>
 ostream& operator<<(ostream& os, const vector<T>& v)
 {
-    copy(v.begin(), v.end(), ostream_iterator<T>(cout, " ")); 
+    copy(v.begin(), v.end(), ostream_iterator<T>(os, " ")); 
     return os;
 }
 
@@ -27,13 +27,16 @@ int main(int ac, char* av[])
 {
     try {
         int opt;
+        string config_file;
     
         // Declare a group of options that will be 
         // allowed only on command line
         po::options_description generic("Generic options");
         generic.add_options()
             ("version,v", "print version string")
-            ("help", "produce help message")    
+            ("help", "produce help message")
+            ("config,c", po::value<string>(&config_file)->default_value("multiple_sources.cfg"),
+                  "name of a file of a configuration.")
             ;
     
         // Declare a group of options that will be 
@@ -71,10 +74,19 @@ int main(int ac, char* av[])
         po::variables_map vm;
         store(po::command_line_parser(ac, av).
               options(cmdline_options).positional(p).run(), vm);
-
-        ifstream ifs("multiple_sources.cfg");
-        store(parse_config_file(ifs, config_file_options), vm);
         notify(vm);
+        
+        ifstream ifs(config_file.c_str());
+        if (!ifs)
+        {
+            cout << "can not open config file: " << config_file << "\n";
+            return 0;
+        }
+        else
+        {
+            store(parse_config_file(ifs, config_file_options), vm);
+            notify(vm);
+        }
     
         if (vm.count("help")) {
             cout << visible << "\n";

example/option_groups.cpp

@@ -29,9 +29,9 @@ using namespace boost::program_options;
 
 #include <iostream>
 #include <fstream>
+#include <exception>
 using namespace std;
 
-
 int main(int ac, char* av[])
 {
     try {
@@ -39,7 +39,7 @@ int main(int ac, char* av[])
         options_description general("General options");
         general.add_options()
             ("help", "produce a help message")
-            ("help-module", value<string>()->implicit(),
+            ("help-module", value<string>(),
                 "produce a help for a given module")
             ("version", "output the version number")
             ;
@@ -91,7 +91,7 @@ int main(int ac, char* av[])
                  << vm["num-threads"].as<int>() << "\n";            
         }                           
     }
-    catch(exception& e) {
+    catch(std::exception& e) {
         cout << e.what() << "\n";
     }
 }

example/options_description.cpp

@@ -18,7 +18,7 @@ using namespace std;
 template<class T>
 ostream& operator<<(ostream& os, const vector<T>& v)
 {
-    copy(v.begin(), v.end(), ostream_iterator<T>(cout, " ")); 
+    copy(v.begin(), v.end(), ostream_iterator<T>(os, " "));
     return os;
 }
 
@@ -26,24 +26,30 @@ int main(int ac, char* av[])
 {
     try {
         int opt;
+        int portnum;
         po::options_description desc("Allowed options");
         desc.add_options()
             ("help", "produce help message")
-            ("optimization", po::value<int>(&opt)->default_value(10), 
+            ("optimization", po::value<int>(&opt)->default_value(10),
                   "optimization level")
-            ("include-path,I", po::value< vector<string> >(), 
+            ("verbose,v", po::value<int>()->implicit_value(1),
+                  "enable verbosity (optionally specify level)")
+            ("listen,l", po::value<int>(&portnum)->implicit_value(1001)
+                  ->default_value(0,"no"),
+                  "listen on a port.")
+            ("include-path,I", po::value< vector<string> >(),
                   "include path")
             ("input-file", po::value< vector<string> >(), "input file")
         ;
 
         po::positional_options_description p;
         p.add("input-file", -1);
-        
+
         po::variables_map vm;
         po::store(po::command_line_parser(ac, av).
                   options(desc).positional(p).run(), vm);
         po::notify(vm);
-    
+
         if (vm.count("help")) {
             cout << "Usage: options_description [options]\n";
             cout << desc;
@@ -52,22 +58,29 @@ int main(int ac, char* av[])
 
         if (vm.count("include-path"))
         {
-            cout << "Include paths are: " 
+            cout << "Include paths are: "
                  << vm["include-path"].as< vector<string> >() << "\n";
         }
 
         if (vm.count("input-file"))
         {
-            cout << "Input files are: " 
+            cout << "Input files are: "
                  << vm["input-file"].as< vector<string> >() << "\n";
         }
 
-        cout << "Optimization level is " << opt << "\n";                
+        if (vm.count("verbose")) {
+            cout << "Verbosity enabled.  Level is " << vm["verbose"].as<int>()
+                 << "\n";
+        }
+
+        cout << "Optimization level is " << opt << "\n";
+
+        cout << "Listen port is " << portnum << "\n";
     }
-    catch(exception& e)
+    catch(std::exception& e)
     {
         cout << e.what() << "\n";
         return 1;
-    }    
+    }
     return 0;
 }

example/options_heirarchy.cpp

@@ -0,0 +1,690 @@
+// Copyright Thomas Kent 2016
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+// 
+// This is an example of a program that uses multiple facets of the boost
+// program_options library. It will go through different types of config 
+// options in a heirarchal manner:
+// 1. Default options are set.
+// 2. Command line options are set (they override defaults).
+// 3. Environment options are set (they override defaults but not command
+//    line options).
+// 4. Config files specified on the command line are read, if present, in
+//    the order specified. (these override defaults but not options from the
+//    other steps).
+// 5. Default config file (default.cfg) is read, if present (it overrides
+//    defaults but not options from the other steps).
+// 
+// See the bottom of this file for full usage examples
+//
+
+#include <boost/program_options.hpp>
+namespace po = boost::program_options;
+#include <string>
+#include <iostream>
+#include <map>
+#include <stdexcept>
+#include <fstream>
+
+const std::string version("1.0");
+
+// Used to exit the program if the help/version option is set
+class OptionsExitsProgram : public std::exception
+{};
+
+struct GuiOpts
+{
+   unsigned int width;
+   unsigned int height;
+};
+
+struct NetworkOpts
+{
+   std::string address;
+   unsigned short port;
+};
+
+class OptionsHeirarchy
+{
+public:
+   // The constructor sets up all the various options that will be parsed
+   OptionsHeirarchy()
+   {
+      SetOptions();
+   }
+
+   // Parse options runs through the heirarchy doing all the parsing
+   void ParseOptions(int argc, char* argv[])
+   {
+      ParseCommandLine(argc, argv);
+      CheckForHelp();
+      CheckForVersion();
+      ParseEnvironment();
+      ParseConfigFiles();
+      ParseDefaultConfigFile();
+   }
+
+   // Below is the interface to access the data, once ParseOptions has been run
+   std::string Path()
+   {
+      return results["path"].as<std::string>();
+   }
+   std::string Verbosity()
+   {
+      return results["verbosity"].as<std::string>();
+   }
+   std::vector<std::string> IncludePath()
+   {
+      if (results.count("include-path"))
+      {
+         return results["include-path"].as<std::vector<std::string>>();
+      }
+      return std::vector<std::string>();
+   }
+   std::string MasterFile()
+   {
+      if (results.count("master-file"))
+      {
+         return results["master-file"].as<std::string>();
+      }
+      return "";
+   }
+   std::vector<std::string> Files()
+   {
+      if (results.count("file"))
+      {
+         return results["file"].as<std::vector<std::string>>();
+      }
+      return std::vector<std::string>();
+   }
+   bool GUI()
+   {
+      if (results["run-gui"].as<bool>())
+      {
+         return true;
+      }
+      return false;
+   }
+   GuiOpts GuiValues()
+   {
+      GuiOpts opts;
+      opts.width = results["gui.width"].as<unsigned int>();
+      opts.height = results["gui.height"].as<unsigned int>();
+      return opts;
+   }
+   NetworkOpts NetworkValues()
+   {
+      NetworkOpts opts;
+      opts.address = results["network.ip"].as<std::string>();
+      opts.port = results["network.port"].as<unsigned short>();
+      return opts;
+   }
+
+private:
+   void SetOptions()
+   {
+      SetCommandLineOptions();
+      SetCommonOptions();
+      SetConfigOnlyOptions();
+      SetEnvMapping();
+   }
+   void SetCommandLineOptions()
+   {
+      command_line_options.add_options()
+         ("help,h", "display this help message")
+         ("version,v", "show program version")
+         ("config,c", po::value<std::vector<std::string>>(),
+            "config files to parse (always parses default.cfg)")
+         ;
+      hidden_command_line_options.add_options()
+         ("master-file", po::value<std::string>())
+         ("file", po::value<std::vector<std::string>>())
+         ;
+      positional_options.add("master-file", 1);
+      positional_options.add("file", -1);
+   }
+   void SetCommonOptions()
+   {
+      common_options.add_options()
+         ("path", po::value<std::string>()->default_value(""),
+            "the execution path to use (imports from environment if not specified)")
+         ("verbosity", po::value<std::string>()->default_value("INFO"),
+            "set verbosity: DEBUG, INFO, WARN, ERROR, FATAL")
+         ("include-path,I", po::value<std::vector<std::string>>()->composing(),
+            "paths to search for include files")
+         ("run-gui", po::bool_switch(), "start the GUI")
+         ;
+   }
+   void SetConfigOnlyOptions()
+   {
+      config_only_options.add_options()
+         ("log-dir", po::value<std::string>()->default_value("log"))
+         ("gui.height", po::value<unsigned int>()->default_value(100))
+         ("gui.width", po::value<unsigned int>()->default_value(100))
+         ("network.ip", po::value<std::string>()->default_value("127.0.0.1"))
+         ("network.port", po::value<unsigned short>()->default_value(12345))
+         ;
+      // Run a parser here (with no command line options) to add these defaults into
+      // results, this way they will be enabled even if no config files are parsed.
+      store(po::command_line_parser(0, 0).options(config_only_options).run(), results);
+      notify(results);
+   }
+   void SetEnvMapping()
+   {
+      env_to_option["PATH"] = "path";
+      env_to_option["EXAMPLE_VERBOSE"] = "verbosity";
+   }
+
+
+   void ParseCommandLine(int argc, char* argv[])
+   {
+      po::options_description cmd_opts;
+      cmd_opts.add(command_line_options).add(hidden_command_line_options).add(common_options);
+      store(po::command_line_parser(argc, argv).
+         options(cmd_opts).positional(positional_options).run(), results);
+      notify(results);
+   }
+   void CheckForHelp()
+   {
+      if (results.count("help"))
+      {
+         PrintHelp();
+      }
+   }
+   void PrintHelp()
+   {
+      std::cout << "Program Options Example" << std::endl;
+      std::cout << "Usage: example [OPTION]... MASTER-FILE [FILE]...\n";
+      std::cout << "  or   example [OPTION] --run-gui\n";
+      po::options_description help_opts;
+      help_opts.add(command_line_options).add(common_options);
+      std::cout << help_opts << std::endl;
+      throw OptionsExitsProgram();
+   }
+   void CheckForVersion()
+   {
+      if (results.count("version"))
+      {
+         PrintVersion();
+      }
+   }
+   void PrintVersion()
+   {
+      std::cout << "Program Options Example " << version << std::endl;
+      throw OptionsExitsProgram();
+   }
+   void ParseEnvironment() 
+   {
+      store(po::parse_environment(common_options,
+         // The next two lines are the crazy syntax to use EnvironmentMapper as
+         // the lookup function for env->config name conversions
+         boost::function1<std::string, std::string>(
+         std::bind1st(std::mem_fun(&OptionsHeirarchy::EnvironmentMapper), this))),
+         results);
+      notify(results);
+   }
+   std::string EnvironmentMapper(std::string env_var)
+   {
+      // ensure the env_var is all caps
+      std::transform(env_var.begin(), env_var.end(), env_var.begin(), ::toupper);
+
+      auto entry = env_to_option.find(env_var);
+      if (entry != env_to_option.end())
+      {
+         return entry->second;
+      }
+      return "";
+   }
+   void ParseConfigFiles()
+   {
+      if (results.count("config"))
+      {
+         auto files = results["config"].as<std::vector<std::string>>();
+         for (auto file = files.begin(); file != files.end(); file++)
+         {
+            LoadAConfigFile(*file);
+         }
+      }
+   }
+   void LoadAConfigFile(std::string filename)
+   {
+      bool ALLOW_UNREGISTERED = true;
+
+      po::options_description config_opts;
+      config_opts.add(config_only_options).add(common_options);
+
+      std::ifstream cfg_file(filename.c_str());
+      if (cfg_file)
+      {
+         store(parse_config_file(cfg_file, config_opts, ALLOW_UNREGISTERED), results);
+         notify(results);
+      }
+   }
+   void ParseDefaultConfigFile()
+   {
+      LoadAConfigFile("default.cfg");
+   }
+
+   std::map<std::string, std::string> env_to_option;
+   po::options_description config_only_options;
+   po::options_description common_options;
+   po::options_description command_line_options;
+   po::options_description hidden_command_line_options;
+   po::positional_options_description positional_options;
+   po::variables_map results;
+};
+
+
+void get_env_options()
+{
+}
+
+void PrintOptions(OptionsHeirarchy options)
+{
+   auto path = options.Path();
+   if (path.length())
+   {
+      std::cout << "First 75 chars of the system path: \n";
+      std::cout << options.Path().substr(0, 75) << std::endl;
+   }
+
+   std::cout << "Verbosity: " << options.Verbosity() << std::endl;
+   std::cout << "Include Path:\n";
+   auto includePaths = options.IncludePath();
+   for (auto path = includePaths.begin(); path != includePaths.end(); path++)
+   {
+      std::cout << "   " << *path << std::endl;
+   }
+   std::cout << "Master-File: " << options.MasterFile() << std::endl;
+   std::cout << "Additional Files:\n";
+   auto files = options.Files();
+   for (auto file = files.begin(); file != files.end(); file++)
+   {
+      std::cout << "   " << *file << std::endl;
+   }
+
+   std::cout << "GUI Enabled: " << std::boolalpha << options.GUI() << std::endl;
+   if (options.GUI())
+   {
+      auto gui_values = options.GuiValues();
+      std::cout << "GUI Height: " << gui_values.height << std::endl;
+      std::cout << "GUI Width: " << gui_values.width << std::endl;
+   }
+
+   auto network_values = options.NetworkValues();
+   std::cout << "Network Address: " << network_values.address << std::endl;
+   std::cout << "Network Port: " << network_values.port << std::endl;
+}
+
+int main(int ac, char* av[])
+{
+   OptionsHeirarchy options;
+   try
+   {
+      options.ParseOptions(ac, av);
+      PrintOptions(options);
+   }
+   catch (OptionsExitsProgram){}
+
+   return 0;
+}
+
+/* 
+Full Usage Examples
+===================
+
+These were run on windows, so some results may show that environment, but 
+results should be similar on POSIX platforms.
+
+Help
+----
+To see the help screen, with the available options just pass the --help (or -h) 
+parameter. The program will then exit.
+
+    > example.exe --help
+    Program Options Example
+    Usage: example [OPTION]... MASTER-FILE [FILE]...
+      or   example [OPTION] --run-gui
+
+      -h [ --help ]              display this help message
+      -v [ --version ]           show program version
+      -c [ --config ] arg        config files to parse (always parses default.cfg)
+
+      --path arg                 the execution path to use (imports from
+                                 environment if not specified)
+      --verbosity arg (=INFO)    set verbosity: DEBUG, INFO, WARN, ERROR, FATAL
+      -I [ --include-path ] arg  paths to search for include files
+      --run-gui                  start the GUI
+
+Version is similar to help (--version or -v).
+
+    > example.exe -v
+    Program Options Example 1.0
+
+Basics
+------
+Running without any options will get the default values (path is set from the 
+environment):
+
+    > example.exe 
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+We can easily override that environment path with a simple option:
+
+    > example.exe --path a/b/c;d/e/f
+    First 75 chars of the system path:
+    a/b/c;d/e/f
+    Verbosity: INFO
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+You can use a space or equals sign after long options, also backslashes are
+treated literally on windows, on POSIX they need to be escaped.
+
+    > example.exe --path=a\b\c\;d\e\\f
+    First 75 chars of the system path:
+    a\b\c\;d\e\\f
+    Verbosity: INFO
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+For short options you can use a space:
+
+    > example.exe -I path/to/includes
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+        path\to\includes
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+Or you can put the option immediately after it:
+
+    > example.exe -Ipath/to/includes
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+        path\to\includes
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+The include path (--include-path or -I) option allows for multiple paths to be 
+specified (both on the command line and in config files) and combined into a 
+vector for use by the program.
+
+    > example.exe --include-path=a/b/c --include-path d/e/f -I g/h/i -Ij/k/l
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+       a/b/c
+       d/e/f
+       g/h/i
+       j/k/l
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+There are also the option of flags that do not take parameters and just set a 
+boolean value to true. In this case, running the gui also causes default values
+for the gui to be output to the screen.
+
+    > example.exe --run-gui
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: true
+    GUI Height: 100
+    GUI Width: 100
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+There are also "positional" options at the end of the command line. The first
+one specifies the "master" file the others are additional files.
+
+    > example.exe --path=a-path -I an-include master.cpp additional1.cpp additional2.cpp
+    First 75 chars of the system path:
+    a-path
+    Verbosity: INFO
+    Include Path:
+       an-include
+    Master-File: master.cpp
+    Additional Files:
+       additional1.cpp
+       additional2.cpp
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+Environment Variables
+---------------------
+In addition to the PATH environment variable, it also knows how to read the 
+EXAMPLE_VERBOSE environmental variable and use that to set the verbosity
+option/
+
+    > set EXAMPLE_VERBOSE=DEBUG
+    > example.exe
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: DEBUG
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+However, if the --verboseity flag is also set, it will override the env
+variable. This illustrates an important example, the way program_options works,
+is that a parser will not override a value that has previously been set by 
+another parser. Thus the env parser doesn't override the command line parser.
+(We will see this again in config files.) Default values are seperate from this
+heirarcy, they only apply if no parser has set the value and it is being read.
+
+    > set EXAMPLE_VERBOSE=DEBUG
+    > example.exe --verbosity=WARN
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: WARN
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+(You can unset an environmental variable with an empty set command)
+   
+    > set EXAMPLE_VERBOSE=
+    > example.exe
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+
+Config Files
+------------
+Config files generally follow the [INI file format]
+(https://en.wikipedia.org/wiki/INI_file) with a few exceptions. 
+
+Values can be simply added tp options with an equal sign. Here are two include
+paths added via the default config file (default.cfg), you can have optional
+spaces around the equal sign.
+
+    # You can use comments in a config file
+    include-path=first/default/path
+    include-path = second/default/path
+
+Results in
+
+    > example.exe
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+       first/default/path
+       second/default/path
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 127.0.0.1
+    Network Port: 12345
+
+Values can also be in sections of the config file. Again, editing default.cfg
+
+    include-path=first/default/path
+    include-path = second/default/path
+
+    [network]
+    ip=1.2.3.4
+    port=3000
+
+Results in
+
+    > example.exe
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: INFO
+    Include Path:
+       first/default/path
+       second/default/path
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 1.2.3.4
+    Network Port: 3000
+
+This example is also setup to allow multiple config files to be specified on
+the command line, which are checked before the default.cfg file is read (but
+after the environment and command line parsing). Thus we can set the first.cfg
+file to contain the following:
+
+    verbosity=ERROR
+
+    [network]
+    ip = 5.6.7.8
+
+Results in:
+
+    > example.exe --config first.cfg
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: ERROR
+    Include Path:
+       first/default/path
+       second/default/path
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 5.6.7.8
+    Network Port: 3000
+
+But since the config files are read after the command line, setting the
+verbosity there causes the value in the file to be ignored.
+
+    > example.exe --config first.cfg --verbosity=WARN
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: WARN
+    Include Path:
+       first/default/path
+       second/default/path
+    Master-File:
+    Additional Files:
+    GUI Enabled: false
+    Network Address: 5.6.7.8
+    Network Port: 3000
+
+The config files are parsed in the order they are received on the command line.
+So adding the second.cfg file:
+
+    verbosity=FATAL
+    run-gui=true
+
+    [gui]
+    height=720
+    width=1280
+
+Results in a combination of all three config files:
+
+    > example.exe --config first.cfg --config second.cfg
+    First 75 chars of the system path:
+    C:\Program Files (x86)\MSBuild\14.0\bin;C:\Perl\site\bin;C:\Perl\bin;C:\Pro
+    Verbosity: ERROR
+    Include Path:
+       first/default/path
+       second/default/path
+    Master-File:
+    Additional Files:
+    GUI Enabled: true
+    GUI Height: 720
+    GUI Width: 1280
+    Network Address: 5.6.7.8
+    Network Port: 3000
+
+Incidently the boolean run-gui option could have been set a number of ways 
+that all result in the C++ boolean value of true:
+
+    run-gui=true
+    run-gui=on
+    run-gui=1
+    run-gui=yes
+    run-gui=
+
+Since run-gui is an option that was set with the bool_switch type, which
+forces its use on the command line without a parameter (i.e. --run-gui instead
+of --run-gui=true) it can't be given a "false" option, bool_switch values can 
+only be turned true. If instead we had a value ("my-switch", po::value<bool>())
+that could be set at the command line --my-switch=true or --my-switch=false, or 
+any of the other types of boolean keywords true: true, on, 1, yes; 
+false: false, off, 0, no. In a config file this could look like:
+
+    my-switch=true
+    my-switch=on
+    my-switch=1
+    my-switch=yes
+    my-switch=
+
+    my-switch=false
+    my-switch=off
+    my-switch=0
+    my-switch=no
+
+*/

example/regex.cpp

@@ -43,7 +43,7 @@ public:
 */
 void validate(boost::any& v, 
               const std::vector<std::string>& values,
-              magic_number* target_type, int)
+              magic_number*, int)
 {
     static regex r("\\d\\d\\d-(\\d\\d\\d)");
 
@@ -61,7 +61,7 @@ void validate(boost::any& v,
     if (regex_match(s, match, r)) {
         v = any(magic_number(lexical_cast<int>(match[1])));
     } else {
-        throw validation_error("invalid value");
+        throw validation_error(validation_error::invalid_option_value);
     }        
 }
 
@@ -94,7 +94,7 @@ int main(int ac, char* av[])
                  << vm["magic"].as<magic_number>().n << "\"\n";
         }
     }
-    catch(exception& e)
+    catch(std::exception& e)
     {
         cout << e.what() << "\n";
     }    

example/response_file.cpp

@@ -46,6 +46,7 @@ int main(int ac, char* av[])
             ("help", "produce a help message")
             ("include-path,I", value< vector<string> >()->composing(), 
                  "include path")
+            ("magic", value<int>(), "magic value")
             ("response-file", value<string>(), 
                  "can be specified with '@name', too")
         ;
@@ -69,7 +70,8 @@ int main(int ac, char* av[])
             ss << ifs.rdbuf();
             // Split the file content
             char_separator<char> sep(" \n\r");
-            tokenizer<char_separator<char> > tok(ss.str(), sep);
+            string sstr = ss.str();
+            tokenizer<char_separator<char> > tok(sstr, sep);
             vector<string> args;
             copy(tok.begin(), tok.end(), back_inserter(args));
             // Parse the file and store the options
@@ -82,8 +84,11 @@ int main(int ac, char* av[])
             copy(s.begin(), s.end(), ostream_iterator<string>(cout, " "));
             cout << "\n";
         }        
+        if (vm.count("magic")) {
+            cout << "Magic value: " << vm["magic"].as<int>() << "\n";
+        }
     }
-    catch(exception& e) {
+    catch (std::exception& e) {
         cout << e.what() << "\n";
     }
 }

example/response_file.rsp

@@ -1,2 +1,3 @@
 -I bar
--I biz
+-I biz
+--magic 10

include/boost/program_options.hpp

@@ -3,10 +3,12 @@
 // accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 
+//  See www.boost.org/libs/program_options for documentation.
+
 #ifndef PROGRAM_OPTIONS_VP_2003_05_19
 #define PROGRAM_OPTIONS_VP_2003_05_19
 
-#if _MSC_VER >= 1020
+#if defined(_MSC_VER)
 #pragma once
 #endif
 

include/boost/program_options/cmdline.hpp

@@ -12,13 +12,13 @@ namespace boost { namespace program_options { namespace command_line_style {
     There are "long" options, which start with "--" and "short",
     which start with either "-" or "/". Both kinds can be allowed or
     disallowed, see allow_long and allow_short. The allowed character
-    for short option is also configurable.
+    for short options is also configurable.
 
-    Option's value can be specified in the same token as value
+    Option's value can be specified in the same token as name
     ("--foo=bar"), or in the next token.
 
-    It's possible to introduce long option by the same character as
-    long option, see allow_long_disguise.
+    It's possible to introduce long options by the same character as
+    short options, see allow_long_disguise.
 
     Finally, guessing (specifying only prefix of option) and case
     insensitive processing are supported.
@@ -26,7 +26,7 @@ namespace boost { namespace program_options { namespace command_line_style {
     enum style_t {
         /// Allow "--long_name" style
         allow_long = 1,
-        /// Alow "-<single character" style
+        /// Allow "-<single character" style
         allow_short = allow_long << 1,
         /// Allow "-" in short options
         allow_dash_for_short = allow_short << 1,
@@ -39,7 +39,7 @@ namespace boost { namespace program_options { namespace command_line_style {
             @endverbatim
         */
         long_allow_adjacent = allow_slash_for_short << 1,
-        /** Allow option parameter in the same token for
+        /** Allow option parameter in the next token for
             long options. */
         long_allow_next = long_allow_adjacent << 1,
         /** Allow option parameter in the same token for
@@ -59,17 +59,22 @@ namespace boost { namespace program_options { namespace command_line_style {
         /** Allow abbreviated spellings for long options,
             if they unambiguously identify long option. 
             No long option name should be prefix of other 
-            long option name is guessing is in effect.
+            long option name if guessing is in effect.
         */
         allow_guessing = allow_sticky << 1,
-        /** Ignore the difference in case for options. 
-            @todo Should this apply to long options only?
+        /** Ignore the difference in case for long options.
         */            
-        case_insensitive = allow_guessing << 1,
+        long_case_insensitive = allow_guessing << 1,        
+        /** Ignore the difference in case for short options.
+        */            
+        short_case_insensitive = long_case_insensitive << 1,
+        /** Ignore the difference in case for all options.
+        */        
+        case_insensitive = (long_case_insensitive | short_case_insensitive),        
         /** Allow long options with single option starting character,
             e.g <tt>-foo=10</tt>
         */
-        allow_long_disguise = case_insensitive << 1,
+        allow_long_disguise = short_case_insensitive << 1,
         /** The more-or-less traditional unix style. */
         unix_style = (allow_short | short_allow_adjacent | short_allow_next
                       | allow_long | long_allow_adjacent | long_allow_next

include/boost/program_options/config.hpp

@@ -8,6 +8,7 @@
 #define BOOST_PROGRAM_OPTIONS_CONFIG_HK_2004_01_11
 
 #include <boost/config.hpp>
+#include <boost/version.hpp>
 
 // Support for autolinking.
 #if BOOST_VERSION >= 103100   // works beginning from Boost V1.31.0
@@ -20,6 +21,10 @@
 // Set the name of our library, this will get undef'ed by auto_link.hpp
 // once it's done with it:
 #define BOOST_LIB_NAME boost_program_options
+// tell the auto-link code to select a dll when required:
+#if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_PROGRAM_OPTIONS_DYN_LINK)
+#  define BOOST_DYN_LINK
+#endif
 
 // And include the header that does the work:
 #include <boost/config/auto_link.hpp>
@@ -29,17 +34,14 @@
 #endif  // BOOST_VERSION
 
 ///////////////////////////////////////////////////////////////////////////////
-// Windows DLL suport
-#ifdef BOOST_HAS_DECLSPEC
 #if defined(BOOST_ALL_DYN_LINK) || defined(BOOST_PROGRAM_OPTIONS_DYN_LINK)
 // export if this is our own source, otherwise import:
 #ifdef BOOST_PROGRAM_OPTIONS_SOURCE
-# define BOOST_PROGRAM_OPTIONS_DECL __declspec(dllexport)
+# define BOOST_PROGRAM_OPTIONS_DECL BOOST_SYMBOL_EXPORT
 #else
-# define BOOST_PROGRAM_OPTIONS_DECL __declspec(dllimport)
+# define BOOST_PROGRAM_OPTIONS_DECL BOOST_SYMBOL_IMPORT
 #endif  // BOOST_PROGRAM_OPTIONS_SOURCE
 #endif  // DYN_LINK
-#endif  // BOOST_HAS_DECLSPEC
 
 #ifndef BOOST_PROGRAM_OPTIONS_DECL
 #define BOOST_PROGRAM_OPTIONS_DECL

include/boost/program_options/detail/cmdline.hpp

@@ -10,6 +10,10 @@
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/errors.hpp>
 #include <boost/program_options/cmdline.hpp>
+#include <boost/program_options/option.hpp>
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/positional_options.hpp>
+
 
 #include <boost/detail/workaround.hpp>
 
@@ -18,6 +22,11 @@
 #include <string>
 #include <vector>
 
+#if defined(BOOST_MSVC)
+#   pragma warning (push)
+#   pragma warning (disable:4251) // class 'std::vector<_Ty>' needs to have dll-interface to be used by clients of class 'boost::program_options::positional_options_description'
+#endif
+
 namespace boost { namespace program_options { namespace detail {
 
     /** Command line parser class. Main requirements were:
@@ -55,6 +64,9 @@ namespace boost { namespace program_options { namespace detail {
         typedef function1<std::pair<std::string, std::string>, 
                           const std::string&> 
             additional_parser;
+
+        typedef function1<std::vector<option>, std::vector<std::string>&>
+            style_parser;
         
         /** Constructs a command line parser for (argc, argv) pair. Uses
             style options passed in 'style', which should be binary or'ed values
@@ -63,12 +75,42 @@ namespace boost { namespace program_options { namespace detail {
             unregistered options. They will be assigned index 1 and are
             assumed to have optional parameter.
         */
-        cmdline(const std::vector<std::string>& args, int style,
-                bool allow_unregistered = false);
+        cmdline(const std::vector<std::string>& args);
 
         /** @overload */
-        cmdline(int argc, const char*const * argv, int style, 
-                bool allow_unregistered = false);
+        cmdline(int argc, const char*const * argv);
+
+        void style(int style);
+
+        /** returns the canonical option prefix associated with the command_line_style
+         *  In order of precedence:
+         *      allow_long           : allow_long
+         *      allow_long_disguise  : allow_long_disguise
+         *      allow_dash_for_short : allow_short | allow_dash_for_short
+         *      allow_slash_for_short: allow_short | allow_slash_for_short
+         *  
+         *      This is mainly used for the diagnostic messages in exceptions
+        */ 
+        int         get_canonical_option_prefix();
+
+        void allow_unregistered();
+
+        void set_options_description(const options_description& desc);
+        void set_positional_options(
+            const positional_options_description& m_positional);
+
+        std::vector<option> run();
+
+        std::vector<option> parse_long_option(std::vector<std::string>& args);
+        std::vector<option> parse_short_option(std::vector<std::string>& args);
+        std::vector<option> parse_dos_option(std::vector<std::string>& args);
+        std::vector<option> parse_disguised_long_option(
+            std::vector<std::string>& args);
+        std::vector<option> parse_terminator(
+            std::vector<std::string>& args);
+        std::vector<option> handle_additional_parser(
+            std::vector<std::string>& args);
+
 
         /** Set additional parser. This will be called for each token
             of command line. If first string in pair is not empty,
@@ -80,208 +122,38 @@ namespace boost { namespace program_options { namespace detail {
         */
         void set_additional_parser(additional_parser p);
 
-        /** Registers a new option.
-            @param long_name Long name to use. When ending '*', symbols up to
-            it give an allowed prefix -- all options starting with it will be
-            allowed. The first character may not be '-'. Empty string means no
-            long name.
-            @param short_name Short name to use. Value of '\0' means no short
-            name.
-            @param properties Tell about possible parameters
-               '|' -- no parameter
-               '?' -- optional parameter
-               ':' -- required parameter
-               '*' -- 0 or more parameters
-               '+' -- 1 or more parameters
-            @param index A distinguishing value for the option.
-            The index will be returned by 'option_index' member function. 
-            Indices need not be unique -- e.g. client can set all indices to 0, 
-            and use the string value to recognize options.
-        */
-        void add_option(const std::string& long_name, char short_name,
-                        char properties = '|', int index = 0);
+        void extra_style_parser(style_parser s);
 
-        /** @overload */
-        void add_option(const char* long_name, char short_name,
-                        char properties = '|', int index = 0);
-
-
-        /** Returns false when nothing more can be extracted */
-        operator bool() const;
-
-        /** Advances to the next element on command line. 
-            When called for the first time, positions on the first element. */
-        cmdline& operator++();
-
-        /// Tells if the current element is option.
-        bool at_option() const;
-
-        /// Tells if the current element is argument.
-        bool at_argument() const;
-
-        /** Returns the option name. If there's long option name associated with
-            this option, it is returned, even if short name was used in command 
-            line.Otherwise, the short name given to 'add_option' is returned 
-            with a '-' prefix. 
-            For purposes of simplicity, '-' is used even when dos-style short 
-            option was found.
-        */
-        const std::string& option_name() const;
-        /** Returns the index for the current option. */
-        int option_index() const;
-        /** Returns the option name as found on the command line. Any symbols
-            that introduce the option, or delimit its parameter will be
-            stripped. This function allows to work with allowed prefixes, in
-            which case 'option_name' will return the prefix specification, and
-            full option name should be queried explicitly.
-            */
-        const std::string& raw_option_name() const;
-        /** Returns the first of option values. If there's more than one option
-            throws multiple_values. If there are no options, returns empty 
-            string. */
-        const std::string& option_value() const;
-        /** Returns all option values. */
-        const std::vector<std::string>& option_values() const;
-        /** Returns the argument. */
-        const std::string& argument() const;
-
-        /** Returns all arguments read by this command line parser. */
-        const std::vector<std::string>& arguments() const;
-
-        /** Returns the token that was current when 'operator++' was
-            last invoked. */
-        const std::string& last() const;
-
-    private:
-
-        // Properties of an option.
-        enum properties_t {
-            no_parameter = 1,
-            /// 0 or 1 parameter
-            allow_parameter,
-            /// exactly 1 parameter
-            require_parameter,
-            /// 0 or more parameters
-            allow_parameters,
-            /// 1 or more parameters 
-            require_parameters
-        };
-
-        enum element_kind_t {
-            ek_option = 0,
-            ek_argument
-        };
-
-        // General error status.
-        enum error_type_t {
-            no_error = 0,
-            unknown_option,
-            ambiguous_option,
-            invalid_syntax
-        };
-
-        // Detailed error status.
-        enum error_description_t {
-            ed_success = 0,
-            ed_long_not_allowed,
-            ed_long_adjacent_not_allowed,
-            ed_short_adjacent_not_allowed,
-            ed_empty_adjacent_parameter,
-            ed_missing_parameter,
-            ed_extra_parameter,
-            ed_unknown_option,
-            ed_ambiguous_option
-        };
-
-        // The standard say that nested classes has no access to
-        // private member of enclosing class. However, most compilers
-        // allow that and it's likely be to allowed in future:
-        // http://std.dkuug.dk/jtc1/sc22/wg21/docs/cwg_defects.html#45  
-        // For Sun compiler, try using friend declaration.
-#if BOOST_WORKAROUND(__SUNPRO_CC, BOOST_TESTED_AT(0x560))
-        struct option;
-        friend struct option;
-#endif
-
-        struct option {
-            option(const std::string& long_name, char short_name,
-                   properties_t properties, int index)
-            : long_name(long_name), short_name(short_name), index(index),
-            properties(properties)
-            {}
-
-            std::string long_name;
-            char short_name;
-            int index;
-            properties_t properties;
-        };
-
-
-        std::vector<option> options;
-
-        void init(const std::vector<std::string>& args, int style,
-                  bool allow_unregistered);
         void check_style(int style) const;
-       
-        void next();
+        
+        bool is_style_active(style_t style) const;
 
-        const option* find_long_option(const char* name);
-        const option* find_short_option(char name);
+        void init(const std::vector<std::string>& args);
 
-        enum option_kind { error_option, no_option, long_option, short_option,
-                           dos_option };
-        option_kind is_option(const char* s);
-        // All handle_* member functions take string without any "--" or "-" or "/"
-        // They return true and success and set m_num_tokens to the number of
-        // tokens that were consumed.
-        bool handle_long_option(const char* s);
-        bool handle_short_option(const char* s, bool ignore_sticky = false);
-        bool handle_dos_option(const char* s);
-        // Attempts to apply additional parser to 's'.
-        bool handle_additional_parser(const std::pair<std::string, std::string>& p);
-
-        bool process_parameter(const option* opt, bool adjacent_parameter,
-                              bool next_parameter);
-        void advance(int count);
-
-        /// Converts parameter property character into enum value.
-        properties_t translate_property(char p);
-
-        /** Clears the error state. If there were an error, throws appripriate
-            exception. */
-        void clear_error();
+        void
+        finish_option(option& opt,
+                      std::vector<std::string>& other_tokens,
+                      const std::vector<style_parser>& style_parsers);
 
         // Copies of input.
-        std::vector<std::string> args;
-        style_t style;
-        bool allow_unregistered;
+        std::vector<std::string> m_args;
+        style_t m_style;
+        bool m_allow_unregistered;
 
-        // Current state of parsing.
-        unsigned index;
-        const char* m_current;
-        const char* m_next;
-        const char* pending_short_option;
-        bool m_no_more_options;
-        error_description_t m_error_description;
-        element_kind_t m_element_kind;
-        int m_option_index;
-
-        // Results of parsing the last option
-        std::string m_last;
-        const option* m_opt;
-        std::string  m_option_name, m_raw_option_name, m_argument;
-        std::vector<std::string> m_option_values; 
-        int m_num_tokens;
-        bool m_disguised_long;
-
-        std::vector<std::string> m_arguments;
+        const options_description* m_desc;
+        const positional_options_description* m_positional;
 
         additional_parser m_additional_parser;
+        style_parser m_style_parser;
     };
     
     void test_cmdline_detail();
     
 }}}
 
+#if defined(BOOST_MSVC)
+#   pragma warning (pop)
+#endif
+
 #endif
 

include/boost/program_options/detail/config_file.hpp

@@ -17,14 +17,21 @@
 #include <boost/program_options/eof_iterator.hpp>
 
 #include <boost/detail/workaround.hpp>
-#if BOOST_WORKAROUND(__MWERKS__, BOOST_TESTED_AT(0x3202))
 #include <boost/program_options/detail/convert.hpp>
+
+#if BOOST_WORKAROUND(__DECCXX_VER, BOOST_TESTED_AT(60590042))
+#include <istream> // std::getline
 #endif
 
 #include <boost/static_assert.hpp>
 #include <boost/type_traits/is_same.hpp>
 #include <boost/shared_ptr.hpp>
 
+#ifdef BOOST_MSVC
+# pragma warning(push)
+# pragma warning(disable: 4251) // class XYZ needs to have dll-interface to be used by clients of class XYZ
+#endif
+
 
 
 namespace boost { namespace program_options { namespace detail {
@@ -60,13 +67,14 @@ namespace boost { namespace program_options { namespace detail {
          TODO: maybe, we should just accept a pointer to options_description
          class.
      */    
-    class common_config_file_iterator 
+    class BOOST_PROGRAM_OPTIONS_DECL common_config_file_iterator
         : public eof_iterator<common_config_file_iterator, option>
     {
     public:
         common_config_file_iterator() { found_eof(); }
         common_config_file_iterator(
-            const std::set<std::string>& allowed_options);
+            const std::set<std::string>& allowed_options,
+            bool allow_unregistered = false);
 
         virtual ~common_config_file_iterator() {}
 
@@ -74,6 +82,11 @@ namespace boost { namespace program_options { namespace detail {
         
         void get();
         
+#if BOOST_WORKAROUND(_MSC_VER, <= 1900)
+        void decrement() {}
+        void advance(difference_type) {}
+#endif
+
     protected: // Stubs for derived classes
 
         // Obtains next line from the config file
@@ -99,6 +112,7 @@ namespace boost { namespace program_options { namespace detail {
         // Invariant: no element is prefix of other element.
         std::set<std::string> allowed_prefixes;
         std::string m_prefix;
+        bool m_allow_unregistered;
     };
 
     template<class charT>
@@ -112,7 +126,8 @@ namespace boost { namespace program_options { namespace detail {
         /** Creates a config file parser for the specified stream.            
         */
         basic_config_file_iterator(std::basic_istream<charT>& is, 
-                                   const std::set<std::string>& allowed_options); 
+                                   const std::set<std::string>& allowed_options,
+                                   bool allow_unregistered = false); 
 
     private: // base overrides
 
@@ -135,8 +150,9 @@ namespace boost { namespace program_options { namespace detail {
     template<class charT>
     basic_config_file_iterator<charT>::
     basic_config_file_iterator(std::basic_istream<charT>& is, 
-                               const std::set<std::string>& allowed_options)
-    : common_config_file_iterator(allowed_options)
+                               const std::set<std::string>& allowed_options,
+                               bool allow_unregistered)
+    : common_config_file_iterator(allowed_options, allow_unregistered)
     {
         this->is.reset(&is, null_deleter());                 
         get();
@@ -160,7 +176,8 @@ namespace boost { namespace program_options { namespace detail {
     }
 
     // Specialization is needed to workaround getline bug on Comeau.
-#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303))
+#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303)) || \
+        (defined(__sgi) && BOOST_WORKAROUND(_COMPILER_VERSION, BOOST_TESTED_AT(741)))
     template<>
     bool
     basic_config_file_iterator<wchar_t>::getline(std::string& s);
@@ -170,4 +187,8 @@ namespace boost { namespace program_options { namespace detail {
 
 }}}
 
+#ifdef BOOST_MSVC
+# pragma warning(pop)
+#endif
+
 #endif

include/boost/program_options/detail/convert.hpp

@@ -19,7 +19,7 @@
 #include <cwchar>
 #include <stdexcept>
 
-#if BOOST_WORKAROUND(__ICL, <= 700) || BOOST_WORKAROUND(_MSC_VER, <= 1200)
+#if defined(BOOST_NO_STDC_NAMESPACE)
 #include <wchar.h>
 namespace std
 {

include/boost/program_options/detail/parsers.hpp

@@ -8,37 +8,24 @@
 
 #include <boost/program_options/detail/convert.hpp>
 
-namespace boost { namespace program_options {
+#include <iterator>
 
-    namespace detail {
-        template<class charT, class Iterator>
-        std::vector<std::basic_string<charT> > 
-        make_vector(Iterator i, Iterator e)
-        {
-            std::vector<std::basic_string<charT> > result;
-            // Some compilers don't have templated constructor for 
-            // vector, so we can't create vector from (argv+1, argv+argc) range
-            for(; i != e; ++i)
-                result.push_back(*i);
-            return result;            
-        }
-    }
+namespace boost { namespace program_options {
 
     template<class charT>
     basic_command_line_parser<charT>::
     basic_command_line_parser(const std::vector<
-                              std::basic_string<charT> >& args)
-    : common_command_line_parser(to_internal(args))
+                              std::basic_string<charT> >& xargs)
+       : detail::cmdline(to_internal(xargs))
     {}
 
 
     template<class charT>
     basic_command_line_parser<charT>::
-    basic_command_line_parser(int argc, charT* argv[])
-    : common_command_line_parser(
-        // Explicit template arguments are required by gcc 3.3.1 
-        // (at least mingw version), and do no harm on other compilers.
-        to_internal(detail::make_vector<charT, charT**>(argv+1, argv+argc)))
+    basic_command_line_parser(int argc, const charT* const argv[])
+    : detail::cmdline(
+        to_internal(std::vector<std::basic_string<charT> >(argv+1, argv+argc))),
+        m_desc()
     {}
 
     
@@ -46,6 +33,7 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>& 
     basic_command_line_parser<charT>::options(const options_description& desc)
     {
+        detail::cmdline::set_options_description(desc);
         m_desc = &desc;
         return *this;
     }
@@ -55,15 +43,15 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>::positional(
         const positional_options_description& desc)
     {
-        m_positional = &desc;
+        detail::cmdline::set_positional_options(desc);
         return *this;
     }
 
     template<class charT>
     basic_command_line_parser<charT>& 
-    basic_command_line_parser<charT>::style(int style)
+    basic_command_line_parser<charT>::style(int xstyle)
     {
-        m_style = style;
+        detail::cmdline::style(xstyle);
         return *this;
     }
 
@@ -71,24 +59,48 @@ namespace boost { namespace program_options {
     basic_command_line_parser<charT>& 
     basic_command_line_parser<charT>::extra_parser(ext_parser ext)
     {
-        m_ext = ext;
+        detail::cmdline::set_additional_parser(ext);
         return *this;
     }
 
+    template<class charT>
+    basic_command_line_parser<charT>& 
+    basic_command_line_parser<charT>::allow_unregistered()
+    {
+        detail::cmdline::allow_unregistered();
+        return *this;
+    }
+
+    template<class charT>
+    basic_command_line_parser<charT>& 
+    basic_command_line_parser<charT>::extra_style_parser(style_parser s)
+    {
+        detail::cmdline::extra_style_parser(s);
+        return *this;
+    }
+
+
+
     template<class charT>    
     basic_parsed_options<charT>
-    basic_command_line_parser<charT>::run() const
+    basic_command_line_parser<charT>::run()
     {
+        // save the canonical prefixes which were used by this cmdline parser
+        //    eventually inside the parsed results
+        //    This will be handy to format recognisable options
+        //    for diagnostic messages if everything blows up much later on
+        parsed_options result(m_desc, detail::cmdline::get_canonical_option_prefix());
+        result.options = detail::cmdline::run();
+
         // Presense of parsed_options -> wparsed_options conversion
         // does the trick.
-        return basic_parsed_options<charT>(
-            common_command_line_parser::run());
+        return basic_parsed_options<charT>(result);
     }
 
 
     template<class charT>
     basic_parsed_options<charT>
-    parse_command_line(int argc, charT* argv[],
+    parse_command_line(int argc, const charT* const argv[],
                        const options_description& desc,
                        int style,
                        function1<std::pair<std::string, std::string>, 
@@ -98,6 +110,26 @@ namespace boost { namespace program_options {
             style(style).extra_parser(ext).run();
     }
 
+    template<class charT>
+    std::vector< std::basic_string<charT> > 
+    collect_unrecognized(const std::vector< basic_option<charT> >& options,
+                         enum collect_unrecognized_mode mode)
+    {
+        std::vector< std::basic_string<charT> >  result;
+        for(unsigned i = 0; i < options.size(); ++i)
+        {
+            if (options[i].unregistered ||
+                (mode == include_positional && options[i].position_key != -1))
+            {
+                copy(options[i].original_tokens.begin(),
+                     options[i].original_tokens.end(),
+                     back_inserter(result));
+            }
+        }
+        return result;
+    }
+
+
 }}
 
 #endif

include/boost/program_options/detail/utf8_codecvt_facet.hpp

@@ -1,217 +1,25 @@
-#ifndef BOOST_UTF8_CODECVT_FACET_HPP
-#define BOOST_UTF8_CODECVT_FACET_HPP
-
-// MS compatible compilers support #pragma once
-#if defined(_MSC_VER) && (_MSC_VER >= 1020)
-# pragma once
-#endif
-
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// utf8_codecvt_facet.hpp
-
-// Copyright © 2001 Ronald Garcia, Indiana University (garcia@osl.iu.edu)
+// Copyright (c) 2001 Ronald Garcia, Indiana University (garcia@osl.iu.edu)
 // Andrew Lumsdaine, Indiana University (lums@osl.iu.edu). Permission to copy, 
 // use, modify, sell and distribute this software is granted provided this
 // copyright notice appears in all copies. This software is provided "as is"
 // without express or implied warranty, and with no claim as to its suitability
 // for any purpose.
 
-// Note:(Robert Ramey).  I have made the following alterations in the original
-// code.
-// a) Rendered utf8_codecvt<wchar_t, char>  with using templates
-// b) Move longer functions outside class definition to prevent inlining
-// and make code smaller
-// c) added on a derived class to permit translation to/from current
-// locale to utf8
-
-//  See http://www.boost.org for updates, documentation, and revision history.
-
-// archives stored as text - note these ar templated on the basic
-// stream templates to accommodate wide (and other?) kind of characters
-//
-// note the fact that on libraries without wide characters, ostream is
-// is not a specialization of basic_ostream which in fact is not defined
-// in such cases.   So we can't use basic_ostream<OStream::char_type> but rather
-// use two template parameters
-//
-// utf8_codecvt_facet
-//   This is an implementation of a std::codecvt facet for translating 
-//   from UTF-8 externally to UCS-4.  Note that this is not tied to
-//   any specific types in order to allow customization on platforms
-//   where wchar_t is not big enough.
-//
-// NOTES:  The current implementation jumps through some unpleasant hoops in
-// order to deal with signed character types.  As a std::codecvt_base::result,
-// it is necessary  for the ExternType to be convertible to unsigned  char.
-// I chose not to tie the extern_type explicitly to char. But if any combination
-// of types other than <wchar_t,char_t> is used, then std::codecvt must be
-// specialized on those types for this to work.
-
-#include <locale>
-// for mbstate_t
-#include <wchar.h>
+#ifndef BOOST_PROGRAM_OPTIONS_UTF8_CODECVT_FACET_HPP
+#define BOOST_PROGRAM_OPTIONS_UTF8_CODECVT_FACET_HPP
 
 #include <boost/program_options/config.hpp>
 
-#include <boost/detail/workaround.hpp>
-#if BOOST_WORKAROUND(__BORLANDC__,BOOST_TESTED_AT(0x551))
-    #ifndef _RWSTD_NO_NAMESPACE
-    using std::codecvt;
-    using std::min;
-    #ifdef _RWSTD_NO_MBSTATE_T
-    using std::mbstate_t;
-    #endif
-    #endif
-#elif defined(__COMO__) || defined(_MSC_VER) && _MSC_VER <= 1300 
-    typedef ::mbstate_t mbstate_t;
-#elif defined(BOOST_NO_STDC_NAMESPACE)
-    typedef std::mbstate_t mbstate_t;
-    namespace std{ 
-        using ::codecvt; 
-    } // namespace std
+#define BOOST_UTF8_BEGIN_NAMESPACE \
+     namespace boost { namespace program_options { namespace detail {
+
+#define BOOST_UTF8_END_NAMESPACE }}}
+#define BOOST_UTF8_DECL BOOST_PROGRAM_OPTIONS_DECL
+
+#include <boost/detail/utf8_codecvt_facet.hpp>
+
+#undef BOOST_UTF8_BEGIN_NAMESPACE
+#undef BOOST_UTF8_END_NAMESPACE
+#undef BOOST_UTF8_DECL
+
 #endif
-
-// maximum lenght of a multibyte string
-#define MB_LENGTH_MAX 8
-
-namespace boost { namespace program_options { namespace detail {
-
-struct BOOST_PROGRAM_OPTIONS_DECL utf8_codecvt_facet_wchar_t :
-    public std::codecvt<wchar_t, char, mbstate_t>  
-{
-public:
-    explicit utf8_codecvt_facet_wchar_t(std::size_t no_locale_manage=0)
-        : std::codecvt<wchar_t, char, mbstate_t>(no_locale_manage) 
-    {}
-protected:
-    virtual std::codecvt_base::result do_in(
-        mbstate_t& state, 
-        const char * from,
-        const char * from_end, 
-        const char * & from_next,
-        wchar_t * to, 
-        wchar_t * to_end, 
-        wchar_t*& to_next
-    ) const;
-
-    virtual std::codecvt_base::result do_out(
-        mbstate_t & state, const wchar_t * from,
-        const wchar_t * from_end, const wchar_t*  & from_next,
-        char * to, char * to_end, char * & to_next
-    ) const;
-
-    bool invalid_continuing_octet(unsigned char octet_1) const {
-        return (octet_1 < 0x80|| 0xbf< octet_1);
-    }
-
-    bool invalid_leading_octet(unsigned char octet_1)   const {
-        return (0x7f < octet_1 && octet_1 < 0xc0) ||
-            (octet_1 > 0xfd);
-    }
-
-    // continuing octets = octets except for the leading octet
-    static unsigned int get_cont_octet_count(unsigned   char lead_octet) {
-        return get_octet_count(lead_octet) - 1;
-    }
-
-    static unsigned int get_octet_count(unsigned char   lead_octet);
-
-    // How many "continuing octets" will be needed for this word
-    // ==   total octets - 1.
-    int get_cont_octet_out_count(wchar_t word) const ;
-
-    virtual bool do_always_noconv() const throw() { return false; }
-
-    // UTF-8 isn't really stateful since we rewind on partial conversions
-    virtual std::codecvt_base::result do_unshift(
-        mbstate_t&,
-        char * from,
-        char * to,
-        char * & next
-    ) const 
-    {
-        next = from;
-        return ok;
-    }
-
-    virtual int do_encoding() const throw() {
-        const int variable_byte_external_encoding=0;
-        return variable_byte_external_encoding;
-    }
-
-    // How many char objects can I process to get <= max_limit
-    // wchar_t objects?
-    virtual int do_length(
-        mbstate_t &,
-        const char * from,
-        const char * from_end, 
-        std::size_t max_limit
-    ) const;
-
-    // Largest possible value do_length(state,from,from_end,1) could return.
-    virtual int do_max_length() const throw () {
-        return 6; // largest UTF-8 encoding of a UCS-4 character
-    }
-};
-
-#if 0 // not used - incorrect in any case
-// Robert Ramey - use the above to make a code converter from multi-byte
-// char strings to utf8 encoding
-struct utf8_codecvt_facet_char : public utf8_codecvt_facet_wchar_t
-{
-    typedef utf8_codecvt_facet_wchar_t base_class;
-public:
-    explicit utf8_codecvt_facet_char(size_t no_locale_manage=0)
-        : base_class(no_locale_manage)
-    {}
-protected:
-    virtual std::codecvt_base::result do_in(
-        mbstate_t & state, 
-        const char * from, 
-        const char * from_end, 
-        const char * & from_next,
-        char * to, 
-        char * to_end, 
-        char * & to_next
-    ) const;
-
-    virtual std::codecvt_base::result do_out(
-        mbstate_t & state, 
-        const char * from,
-        const char * from_end, 
-        const char*  & from_next,
-        char * to, 
-        char * to_end, 
-        char * & to_next
-    ) const;
-
-    // How many char objects can I process to get <= max_limit
-    // char objects?
-    virtual int do_length(
-        const mbstate_t&, 
-        const char * from,
-        const char * from_end, 
-        size_t max_limit
-    ) const;
-};
-#endif
-
-template<class Internal, class External>
-struct utf8_codecvt_facet
-{};
-
-template<>
-struct BOOST_PROGRAM_OPTIONS_DECL utf8_codecvt_facet<wchar_t, char>
-    : public utf8_codecvt_facet_wchar_t
-{};
-
-#if 0
-template<>
-struct utf8_codecvt_facet<char, char>
-    : public utf8_codecvt_facet_char
-{};
-#endif
-
-}}}
-
-#endif // BOOST_UTF8_CODECVT_FACET_HPP

include/boost/program_options/detail/value_semantic.hpp

@@ -6,6 +6,11 @@
 // This file defines template functions that are declared in
 // ../value_semantic.hpp.
 
+#include <boost/throw_exception.hpp>
+
+// forward declaration
+namespace boost { template<class T> class optional; }
+
 namespace boost { namespace program_options { 
 
     extern BOOST_PROGRAM_OPTIONS_DECL std::string arg;
@@ -14,10 +19,17 @@ namespace boost { namespace program_options {
     std::string
     typed_value<T, charT>::name() const
     {
-        if (!m_default_value.empty() && !m_default_value_as_text.empty()) {
-            return arg + " (=" + m_default_value_as_text + ")";
+        std::string const& var = (m_value_name.empty() ? arg : m_value_name);
+        if (!m_implicit_value.empty() && !m_implicit_value_as_text.empty()) {
+            std::string msg = "[=" + var + "(=" + m_implicit_value_as_text + ")]";
+            if (!m_default_value.empty() && !m_default_value_as_text.empty())
+                msg += " (=" + m_default_value_as_text + ")";
+            return msg;
+        }
+        else if (!m_default_value.empty() && !m_default_value_as_text.empty()) {
+            return var + " (=" + m_default_value_as_text + ")";
         } else {
-            return arg;
+            return var;
         }
     }
 
@@ -25,7 +37,7 @@ namespace boost { namespace program_options {
     void 
     typed_value<T, charT>::notify(const boost::any& value_store) const
     {
-        const T* value = boost::any_cast<const T>(&value_store);
+        const T* value = boost::any_cast<T>(&value_store);
         if (m_store_to) {
             *m_store_to = *value;
         }
@@ -47,13 +59,12 @@ namespace boost { namespace program_options {
         {
             static std::basic_string<charT> empty;
             if (v.size() > 1)
-                throw validation_error("multiple values not allowed");
-            if (v.size() == 1)
+                boost::throw_exception(validation_error(validation_error::multiple_values_not_allowed));
+            else if (v.size() == 1)
                 return v.front();
-            else if (allow_empty)
-                return empty;
-            else
-                throw validation_error("at least one value required");
+            else if (!allow_empty)
+                boost::throw_exception(validation_error(validation_error::at_least_one_value_required));
+            return empty;
         }
 
         /* Throws multiple_occurrences if 'value' is not empty. */
@@ -81,7 +92,7 @@ namespace boost { namespace program_options {
             v = any(lexical_cast<T>(s));
         }
         catch(const bad_lexical_cast&) {
-            throw invalid_option_value(s);
+            boost::throw_exception(invalid_option_value(s));
         }
     }
 
@@ -97,12 +108,9 @@ namespace boost { namespace program_options {
                        int);
 #endif
     // For some reason, this declaration, which is require by the standard,
-    // cause gcc 3.2 to not generate code to specialization defined in
+    // cause msvc 7.1 to not generate code to specialization defined in
     // value_semantic.cpp
-#if ! ( ( BOOST_WORKAROUND(__GNUC__, <= 3) &&\
-          BOOST_WORKAROUND(__GNUC_MINOR__, < 3) ) || \
-        ( BOOST_WORKAROUND(BOOST_MSVC, == 1310) ) \
-      ) 
+#if ! ( BOOST_WORKAROUND(BOOST_MSVC, == 1310) )
     BOOST_PROGRAM_OPTIONS_DECL void validate(boost::any& v, 
                        const std::vector<std::string>& xs,
                        std::string*,
@@ -128,25 +136,52 @@ namespace boost { namespace program_options {
             v = boost::any(std::vector<T>());
         }
         std::vector<T>* tv = boost::any_cast< std::vector<T> >(&v);
-        assert(tv);
+        assert(NULL != tv);
         for (unsigned i = 0; i < s.size(); ++i)
         {
             try {
-                tv->push_back(boost::lexical_cast<T>(s[i]));
+                /* We call validate so that if user provided
+                   a validator for class T, we use it even
+                   when parsing vector<T>.  */
+                boost::any a;
+                std::vector<std::basic_string<charT> > cv;
+                cv.push_back(s[i]);
+                validate(a, cv, (T*)0, 0);                
+                tv->push_back(boost::any_cast<T>(a));
             }
             catch(const bad_lexical_cast& /*e*/) {
-                throw invalid_option_value(s[i]);
+                boost::throw_exception(invalid_option_value(s[i]));
             }
         }
     }
 
+    /** Validates optional arguments. */
+    template<class T, class charT>
+    void validate(boost::any& v,
+                  const std::vector<std::basic_string<charT> >& s,
+                  boost::optional<T>*,
+                  int)
+    {
+        validators::check_first_occurrence(v);
+        validators::get_single_string(s);
+        boost::any a;
+        validate(a, s, (T*)0, 0);
+        v = boost::any(boost::optional<T>(boost::any_cast<T>(a)));
+    }
+
     template<class T, class charT>
     void 
     typed_value<T, charT>::
     xparse(boost::any& value_store, 
            const std::vector<std::basic_string<charT> >& new_tokens) const
     {
-        validate(value_store, new_tokens, (T*)0, 0);
+        // If no tokens were given, and the option accepts an implicit
+        // value, then assign the implicit value as the stored value;
+        // otherwise, validate the user-provided token(s).
+        if (new_tokens.empty() && !m_implicit_value.empty())
+            value_store = m_implicit_value;
+        else
+            validate(value_store, new_tokens, (T*)0, 0);
     }
 
     template<class T>

include/boost/program_options/environment_iterator.hpp

@@ -40,8 +40,9 @@ namespace boost {
                 assert(n != s.npos);
                 value().first = s.substr(0, n);
                 value().second = s.substr(n+1);
-            }            
-            ++m_environment;
+                
+                ++m_environment;
+            }
         }
         
     private:

include/boost/program_options/eof_iterator.hpp

@@ -10,17 +10,17 @@
 
 namespace boost {
 
-    /** The 'eof_iterator' class is useful for constructing forward iterators 
-        in cases where iterator extract data from some source and it's easy 
-        to detect 'eof' -- i.e. the situation where there's no data. One 
+    /** The 'eof_iterator' class is useful for constructing forward iterators
+        in cases where iterator extract data from some source and it's easy
+        to detect 'eof' \-- i.e. the situation where there's no data. One
         apparent example is reading lines from a file.
-        
+
         Implementing such iterators using 'iterator_facade' directly would
-        require to create class with three core operation, a couple of 
-        constructors. When using 'eof_iterator', the derived class should define 
+        require to create class with three core operation, a couple of
+        constructors. When using 'eof_iterator', the derived class should define
         only one method to get new value, plus a couple of constructors.
 
-        The basic idea is that iterator has 'eof' bit. Two iterators are equal 
+        The basic idea is that iterator has 'eof' bit. Two iterators are equal
         only if both have their 'eof' bits set. The 'get' method either obtains
         the new value or sets the 'eof' bit.
 
@@ -33,13 +33,13 @@ namespace boost {
         3. The 'get' method. It should operate this way:
             - look at some 'data pointer' to see if new element is available;
               if not, it should call 'found_eof'.
-            - extract new element and store it at location returned by the 'value' 
+            - extract new element and store it at location returned by the 'value'
                method.
             - advance the data pointer.
 
-        Essentially, the 'get' method has the functionality of both 'increment' 
-        and 'dereference'. It's very good for the cases where data extraction 
-        implicitly moves data pointer, like for stream operation.         
+        Essentially, the 'get' method has the functionality of both 'increment'
+        and 'dereference'. It's very good for the cases where data extraction
+        implicitly moves data pointer, like for stream operation.
     */
     template<class Derived, class ValueType>
     class eof_iterator : public iterator_facade<Derived, const ValueType,
@@ -65,16 +65,20 @@ namespace boost {
         {
             m_at_eof = true;
         }
-        
+
 
     private: // iterator core operations
-        friend class iterator_core_access;
-    
-        void increment() 
+#ifdef __DCC__ 
+        friend class boost::iterator_core_access; 
+#else 
+        friend class iterator_core_access; 	 
+#endif
+
+        void increment()
         {
             static_cast<Derived&>(*this).get();
         }
-    
+
         bool equal(const eof_iterator& other) const
         {
             if (m_at_eof && other.m_at_eof)
@@ -82,14 +86,14 @@ namespace boost {
             else
                 return false;
         }
-        
+
         const ValueType& dereference() const
         {
             return m_value;
         }
 
         bool m_at_eof;
-        ValueType m_value;        
+        ValueType m_value;
     };
 }
 

include/boost/program_options/errors.hpp

@@ -12,83 +12,385 @@
 #include <string>
 #include <stdexcept>
 #include <vector>
+#include <map>
 
 
+#if defined(BOOST_MSVC)
+#   pragma warning (push)
+#   pragma warning (disable:4275) // non dll-interface class 'std::logic_error' used as base for dll-interface class 'boost::program_options::error'
+#   pragma warning (disable:4251) // class 'std::vector<_Ty>' needs to have dll-interface to be used by clients of class 'boost::program_options::ambiguous_option'
+#endif
 
 namespace boost { namespace program_options {
 
+    inline std::string strip_prefixes(const std::string& text)
+    {
+        // "--foo-bar" -> "foo-bar"
+        std::string::size_type i = text.find_first_not_of("-/");
+        if (i == std::string::npos) {
+            return text;
+        } else {
+            return text.substr(i);
+        }
+    }
+
     /** Base class for all errors in the library. */
     class BOOST_PROGRAM_OPTIONS_DECL error : public std::logic_error {
     public:
-        error(const std::string& what) : std::logic_error(what) {}
+        error(const std::string& xwhat) : std::logic_error(xwhat) {}
     };
 
-    class BOOST_PROGRAM_OPTIONS_DECL invalid_syntax : public error {
+
+    /** Class thrown when there are too many positional options. 
+        This is a programming error.
+    */
+    class BOOST_PROGRAM_OPTIONS_DECL too_many_positional_options_error : public error {
     public:
-        invalid_syntax(const std::string& tokens, const std::string& msg)
-        : error(std::string(msg).append(" in '").append(tokens).append("'")),
-          tokens(tokens), msg(msg)                       
-        {}
-
-        // gcc says that throw specification on dtor is loosened
-        // without this line
-        ~invalid_syntax() throw() {}
-
-        // TODO: copy ctor might throw
-        std::string tokens, msg;
-    };
-
-    /** Class thrown when option name is not recognized. */
-    class BOOST_PROGRAM_OPTIONS_DECL unknown_option : public error {
-    public:
-        unknown_option(const std::string& name)
-        : error(std::string("unknown option ").append(name)) 
+        too_many_positional_options_error() 
+         : error("too many positional options have been specified on the command line") 
         {}
     };
 
-    /** Class thrown when there's ambiguity amoung several possible options. */
-    class BOOST_PROGRAM_OPTIONS_DECL ambiguous_option : public error {
+    /** Class thrown when there are programming error related to style */
+    class BOOST_PROGRAM_OPTIONS_DECL invalid_command_line_style : public error {
     public:
-        ambiguous_option(const std::string& name, 
-                         const std::vector<std::string>& alternatives)
-        : error(std::string("ambiguous option ").append(name)),
-          alternatives(alternatives)
+        invalid_command_line_style(const std::string& msg)
+        : error(msg)
         {}
-
-        ~ambiguous_option() throw() {}
-
-        // TODO: copy ctor might throw
-        std::vector<std::string> alternatives;
     };
 
+    /** Class thrown if config file can not be read */
+    class BOOST_PROGRAM_OPTIONS_DECL reading_file : public error {
+    public:
+        reading_file(const char* filename)
+         : error(std::string("can not read options configuration file '").append(filename).append("'"))
+        {}
+    };
+
+
+    /** Base class for most exceptions in the library.
+     *  
+     *  Substitutes the values for the parameter name
+     *      placeholders in the template to create the human
+     *      readable error message
+     *  
+     *  Placeholders are surrounded by % signs: %example%
+     *      Poor man's version of boost::format
+     *  
+     *  If a parameter name is absent, perform default substitutions
+     *      instead so ugly placeholders are never left in-place.
+     *  
+     *  Options are displayed in "canonical" form
+     *      This is the most unambiguous form of the
+     *      *parsed* option name and would correspond to
+     *      option_description::format_name()
+     *      i.e. what is shown by print_usage()
+     *  
+     *  The "canonical" form depends on whether the option is
+     *      specified in short or long form, using dashes or slashes
+     *      or without a prefix (from a configuration file)
+     *  
+     *   */
+    class BOOST_PROGRAM_OPTIONS_DECL error_with_option_name : public error {
+
+    protected:
+        /** can be
+         *      0 = no prefix (config file options)
+         *      allow_long
+         *      allow_dash_for_short
+         *      allow_slash_for_short
+         *      allow_long_disguise */
+        int m_option_style;
+
+
+        /** substitutions
+         *  from placeholders to values */
+        std::map<std::string, std::string> m_substitutions;
+        typedef std::pair<std::string, std::string> string_pair;
+        std::map<std::string, string_pair > m_substitution_defaults;
+
+    public:
+		/** template with placeholders */
+		std::string m_error_template;
+
+		error_with_option_name(const std::string& template_,
+                              const std::string& option_name = "",
+                              const std::string& original_token = "",
+                              int option_style               = 0);
+
+        /** gcc says that throw specification on dtor is loosened 
+         *  without this line                                     
+         *  */ 
+        ~error_with_option_name() throw() {}
+
+
+        //void dump() const
+        //{
+        //  std::cerr << "m_substitution_defaults:\n";
+        //  for (std::map<std::string, string_pair>::const_iterator iter = m_substitution_defaults.begin();
+        //        iter != m_substitution_defaults.end(); ++iter)
+        //      std::cerr << "\t" << iter->first << ":" << iter->second.first << "=" << iter->second.second << "\n";
+        //  std::cerr << "m_substitutions:\n";
+        //  for (std::map<std::string, std::string>::const_iterator iter = m_substitutions.begin();
+        //        iter != m_substitutions.end(); ++iter)
+        //      std::cerr << "\t" << iter->first << "=" << iter->second << "\n";
+        //  std::cerr << "m_error_template:\n";
+        //  std::cerr << "\t" << m_error_template << "\n";
+        //  std::cerr << "canonical_option_prefix:[" << get_canonical_option_prefix() << "]\n";
+        //  std::cerr << "canonical_option_name:[" << get_canonical_option_name() <<"]\n";
+        //  std::cerr << "what:[" << what() << "]\n";
+        //}
+
+        /** Substitute
+         *      parameter_name->value to create the error message from
+         *      the error template */
+        void set_substitute(const std::string& parameter_name,  const std::string& value)
+        {           m_substitutions[parameter_name] = value;    }
+
+        /** If the parameter is missing, then make the
+         *      from->to substitution instead */
+        void set_substitute_default(const std::string& parameter_name, 
+                                    const std::string& from,  
+                                    const std::string& to)
+        {           
+            m_substitution_defaults[parameter_name] = std::make_pair(from, to); 
+        }
+
+
+        /** Add context to an exception */
+        void add_context(const std::string& option_name,
+                         const std::string& original_token,
+                         int option_style)
+        {
+            set_option_name(option_name);
+            set_original_token(original_token);
+            set_prefix(option_style);
+        }
+
+        void set_prefix(int option_style)
+        {           m_option_style = option_style;}
+
+        /** Overridden in error_with_no_option_name */
+        virtual void set_option_name(const std::string& option_name)
+        {           set_substitute("option", option_name);}
+
+        std::string get_option_name() const
+        {           return get_canonical_option_name();         }
+
+        void set_original_token(const std::string& original_token)
+        {           set_substitute("original_token", original_token);}
+
+
+        /** Creates the error_message on the fly
+         *      Currently a thin wrapper for substitute_placeholders() */
+        virtual const char* what() const throw();
+
+    protected:
+        /** Used to hold the error text returned by what() */
+        mutable std::string m_message;  // For on-demand formatting in 'what'
+
+        /** Makes all substitutions using the template */
+        virtual void substitute_placeholders(const std::string& error_template) const;
+
+        // helper function for substitute_placeholders
+        void replace_token(const std::string& from, const std::string& to) const;
+
+        /** Construct option name in accordance with the appropriate
+         *  prefix style: i.e. long dash or short slash etc */
+        std::string get_canonical_option_name() const;
+        std::string get_canonical_option_prefix() const;
+    };
+
+
     /** Class thrown when there are several option values, but
         user called a method which cannot return them all. */
-    class BOOST_PROGRAM_OPTIONS_DECL multiple_values : public error {
+    class BOOST_PROGRAM_OPTIONS_DECL multiple_values : public error_with_option_name {
     public:
-        multiple_values(const std::string& what) : error(what) {}
+        multiple_values() 
+         : error_with_option_name("option '%canonical_option%' only takes a single argument"){}
+
+        ~multiple_values() throw() {}
     };
 
     /** Class thrown when there are several occurrences of an
         option, but user called a method which cannot return 
         them all. */
-    class BOOST_PROGRAM_OPTIONS_DECL multiple_occurrences : public error {
+    class BOOST_PROGRAM_OPTIONS_DECL multiple_occurrences : public error_with_option_name {
     public:
-        multiple_occurrences(const std::string& what) : error(what) {}
+        multiple_occurrences() 
+         : error_with_option_name("option '%canonical_option%' cannot be specified more than once"){}
+
+        ~multiple_occurrences() throw() {}
+
     };
 
+    /** Class thrown when a required/mandatory option is missing */
+    class BOOST_PROGRAM_OPTIONS_DECL required_option : public error_with_option_name {
+    public:
+       // option name is constructed by the option_descriptor and never on the fly
+       required_option(const std::string& option_name)
+       : error_with_option_name("the option '%canonical_option%' is required but missing", "", option_name)
+       {
+       }
+
+       ~required_option() throw() {}
+    };
+
+    /** Base class of unparsable options,
+     *  when the desired option cannot be identified.
+     *  
+     *  
+     *  It makes no sense to have an option name, when we can't match an option to the
+     *      parameter
+     *  
+     *  Having this a part of the error_with_option_name hierachy makes error handling
+     *      a lot easier, even if the name indicates some sort of conceptual dissonance!
+     *  
+     *   */
+    class BOOST_PROGRAM_OPTIONS_DECL error_with_no_option_name : public error_with_option_name {
+    public:
+        error_with_no_option_name(const std::string& template_,
+                              const std::string& original_token = "")
+        : error_with_option_name(template_, "", original_token)
+        {
+        }
+
+        /** Does NOT set option name, because no option name makes sense */
+        virtual void set_option_name(const std::string&) {}
+
+        ~error_with_no_option_name() throw() {}
+    };
+
+
+    /** Class thrown when option name is not recognized. */
+    class BOOST_PROGRAM_OPTIONS_DECL unknown_option : public error_with_no_option_name {
+    public:
+        unknown_option(const std::string& original_token = "")
+        : error_with_no_option_name("unrecognised option '%canonical_option%'", original_token)
+        {
+        }
+
+        ~unknown_option() throw() {}
+    };
+
+
+
+    /** Class thrown when there's ambiguity amoung several possible options. */
+    class BOOST_PROGRAM_OPTIONS_DECL ambiguous_option : public error_with_no_option_name {
+    public:
+        ambiguous_option(const std::vector<std::string>& xalternatives)
+        : error_with_no_option_name("option '%canonical_option%' is ambiguous"),
+            m_alternatives(xalternatives)
+        {}
+
+        ~ambiguous_option() throw() {}
+
+        const std::vector<std::string>& alternatives() const throw() {return m_alternatives;}
+
+    protected:
+        /** Makes all substitutions using the template */
+        virtual void substitute_placeholders(const std::string& error_template) const;
+    private:
+        // TODO: copy ctor might throw
+        std::vector<std::string> m_alternatives;
+    };
+
+
+    /** Class thrown when there's syntax error either for command
+     *  line or config file options. See derived children for
+     *  concrete classes. */
+    class BOOST_PROGRAM_OPTIONS_DECL invalid_syntax : public error_with_option_name {
+    public:
+        enum kind_t {
+            long_not_allowed = 30,
+            long_adjacent_not_allowed,
+            short_adjacent_not_allowed,
+            empty_adjacent_parameter,
+            missing_parameter,
+            extra_parameter,
+            unrecognized_line
+        };
+
+        invalid_syntax(kind_t kind, 
+                       const std::string& option_name = "",
+                       const std::string& original_token = "",
+                       int option_style              = 0):
+            error_with_option_name(get_template(kind), option_name, original_token, option_style),
+            m_kind(kind)
+        {
+        }
+
+        ~invalid_syntax() throw() {}
+
+        kind_t kind() const {return m_kind;}
+
+        /** Convenience functions for backwards compatibility */
+        virtual std::string tokens() const {return get_option_name();   }
+    protected:
+        /** Used to convert kind_t to a related error text */
+        std::string get_template(kind_t kind);
+        kind_t m_kind;
+    };
+
+    class BOOST_PROGRAM_OPTIONS_DECL invalid_config_file_syntax : public invalid_syntax {
+    public:
+        invalid_config_file_syntax(const std::string& invalid_line, kind_t kind):
+            invalid_syntax(kind)
+        {
+            m_substitutions["invalid_line"] = invalid_line;
+        }
+
+        ~invalid_config_file_syntax() throw() {}
+
+        /** Convenience functions for backwards compatibility */
+        virtual std::string tokens() const {return m_substitutions.find("invalid_line")->second;    }
+    };
+
+
+    /** Class thrown when there are syntax errors in given command line */
+    class BOOST_PROGRAM_OPTIONS_DECL invalid_command_line_syntax : public invalid_syntax {
+    public:
+        invalid_command_line_syntax(kind_t kind,
+                       const std::string& option_name = "",
+                       const std::string& original_token = "",
+                       int option_style              = 0):
+            invalid_syntax(kind, option_name, original_token, option_style) {}
+        ~invalid_command_line_syntax() throw() {}
+    };
+
+
     /** Class thrown when value of option is incorrect. */
-    class BOOST_PROGRAM_OPTIONS_DECL validation_error : public error {
+    class BOOST_PROGRAM_OPTIONS_DECL validation_error : public error_with_option_name {
     public:
-        validation_error(const std::string& what) : error(what) {}
+        enum kind_t {
+            multiple_values_not_allowed = 30,
+            at_least_one_value_required, 
+            invalid_bool_value,
+            invalid_option_value,
+            invalid_option
+        };
+        
+    public:
+        validation_error(kind_t kind, 
+                   const std::string& option_name = "",
+                   const std::string& original_token = "",
+                   int option_style              = 0):
+        error_with_option_name(get_template(kind), option_name, original_token, option_style),
+        m_kind(kind)
+        {
+        }
+
         ~validation_error() throw() {}
-        void set_option_name(const std::string& option);
-    private:
-        mutable std::string m_message; // For on-demand formatting in 'what'
-        std::string m_option_name; // The name of the option which
-                                   // caused the exception.
-        const char* what() const throw();  
+
+        kind_t kind() const { return m_kind; }
+
+    protected:
+        /** Used to convert kind_t to a related error text */
+        std::string get_template(kind_t kind);
+        kind_t m_kind;
     };
 
+    /** Class thrown if there is an invalid option value given */
     class BOOST_PROGRAM_OPTIONS_DECL invalid_option_value 
         : public validation_error
     {
@@ -99,47 +401,24 @@ namespace boost { namespace program_options {
 #endif
     };
 
-    /** Class thrown when there are too many positional options. */
-    class BOOST_PROGRAM_OPTIONS_DECL too_many_positional_options_error : public error {
+    /** Class thrown if there is an invalid bool value given */
+    class BOOST_PROGRAM_OPTIONS_DECL invalid_bool_value 
+        : public validation_error
+    {
     public:
-        too_many_positional_options_error(const std::string& what) 
-        : error(what) {}
+        invalid_bool_value(const std::string& value);
     };
 
-    /** Class thrown when there are too few positional options. */
-    class BOOST_PROGRAM_OPTIONS_DECL too_few_positional_options_error : public error {
-    public:
-        too_few_positional_options_error(const std::string& what) 
-        : error(what) {}
-    };
 
-    class BOOST_PROGRAM_OPTIONS_DECL invalid_command_line_syntax : public invalid_syntax {
-    public:
-        enum kind_t {
-            long_not_allowed = 30,
-            long_adjacent_not_allowed,
-            short_adjacent_not_allowed,
-            empty_adjacent_parameter,
-            missing_parameter,
-            extra_parameter
-        };
 
-        invalid_command_line_syntax(const std::string& tokens, kind_t kind);
-        kind_t kind() const;
-    protected:
-        static std::string error_message(kind_t kind);
-    private:
-        kind_t m_kind;        
-    };
 
-    class BOOST_PROGRAM_OPTIONS_DECL invalid_command_line_style : public error {
-    public:
-        invalid_command_line_style(const std::string& msg)
-        : error(msg)
-        {}
-    };
+
+    
 
 }}
 
+#if defined(BOOST_MSVC)
+#   pragma warning (pop)
+#endif
 
 #endif

include/boost/program_options/option.hpp

@@ -15,7 +15,7 @@ namespace boost { namespace program_options {
 
     /** Option found in input source.
         Contains a key and a value. The key, in turn, can be a string (name of
-        an option), or an integer (position in input source) -- in case no name
+        an option), or an integer (position in input source) \-- in case no name
         is specified. The latter is only possible for command line.
         The template parameter specifies the type of char used for storing the
         option's value.
@@ -23,10 +23,18 @@ namespace boost { namespace program_options {
     template<class charT>
     class basic_option {
     public:
-        basic_option() : position_key(-1) {}
-        basic_option(const std::string& string_key, 
-               const std::vector< std::string> &value) 
-        : string_key(string_key), value(value)
+        basic_option() 
+        : position_key(-1)
+        , unregistered(false) 
+        , case_insensitive(false)
+        {}
+        basic_option(const std::string& xstring_key, 
+               const std::vector< std::string> &xvalue)
+        : string_key(xstring_key)
+        , position_key(-1)
+        , value(xvalue)
+        , unregistered(false)
+        , case_insensitive(false)
         {}
 
         /** String key of this option. Intentionally independent of the template
@@ -41,6 +49,19 @@ namespace boost { namespace program_options {
         int position_key;
         /** Option's value */
         std::vector< std::basic_string<charT> > value;
+        /** The original unchanged tokens this option was
+            created from. */
+        std::vector< std::basic_string<charT> > original_tokens;
+        /** True if option was not recognized. In that case,
+            'string_key' and 'value' are results of purely
+            syntactic parsing of source. The original tokens can be
+            recovered from the "original_tokens" member.
+        */
+        bool unregistered;
+        /** True if string_key has to be handled
+            case insensitive.
+        */
+        bool case_insensitive;
     };
     typedef basic_option<char> option;
     typedef basic_option<wchar_t> woption;

include/boost/program_options/options_description.hpp

@@ -1,4 +1,5 @@
 // Copyright Vladimir Prus 2002-2004.
+// Copyright Bertolt Mildner 2004.
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -21,9 +22,16 @@
 #include <set>
 #include <map>
 #include <stdexcept>
+#include <utility>
 
 #include <iosfwd>
 
+#if defined(BOOST_MSVC)
+#   pragma warning (push)
+#   pragma warning (disable:4251) // class 'boost::shared_ptr<T>' needs to have dll-interface to be used by clients of class 'boost::program_options::option_description'
+#endif
+
+
 /** Boost namespace */
 namespace boost { 
 /** Namespace for the library. */
@@ -34,7 +42,7 @@ namespace program_options {
         are used only to validate input. Second affect interpretation of the
         option, for example default value for it or function that should be
         called  when the value is finally known. Routines which perform parsing
-        never use second kind of properties -- they are side effect free.
+        never use second kind of properties \-- they are side effect free.
         @sa options_description
     */
     class BOOST_PROGRAM_OPTIONS_DECL option_description {
@@ -54,8 +62,8 @@ namespace program_options {
 
             Alas, derived->base conversion for auto_ptr does not really work,
             see
-            http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf
-            http://std.dkuug.dk/jtc1/sc22/wg21/docs/cwg_defects.html#84
+            http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf
+            http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84
 
             So, we have to use plain old pointers. Besides, users are not
             expected to use the constructor directly.
@@ -64,7 +72,7 @@ namespace program_options {
             The 'name' parameter is interpreted by the following rules:
             - if there's no "," character in 'name', it specifies long name
             - otherwise, the part before "," specifies long name and the part
-            after -- long name.
+            after \-- short name.
         */
         option_description(const char* name,
                            const value_semantic* s);
@@ -77,11 +85,38 @@ namespace program_options {
 
         virtual ~option_description();
 
-        /// Name to be used with short-style option ("-w").
-        const std::string& short_name() const;
+        enum match_result { no_match, full_match, approximate_match };
+
+        /** Given 'option', specified in the input source,
+            returns 'true' if 'option' specifies *this.
+        */
+        match_result match(const std::string& option, bool approx,
+                           bool long_ignore_case, bool short_ignore_case) const;
+
+        /** Returns the key that should identify the option, in
+            particular in the variables_map class.
+            The 'option' parameter is the option spelling from the
+            input source.
+            If option name contains '*', returns 'option'.
+            If long name was specified, it's the long name, otherwise
+            it's a short name with prepended '-'.
+        */
+        const std::string& key(const std::string& option) const;
+
+
+        /** Returns the canonical name for the option description to enable the user to
+            recognised a matching option.
+            1) For short options ('-', '/'), returns the short name prefixed.
+            2) For long options ('--' / '-') returns the first long name prefixed
+            3) All other cases, returns the first long name (if present) or the short
+               name, unprefixed.
+        */
+        std::string canonical_display_name(int canonical_option_style = 0) const;
 
-        /// Name to be used with long-style option ("--whatever").
         const std::string& long_name() const;
+
+        const std::pair<const std::string*, std::size_t> long_names() const;
+
         /// Explanation of this option
         const std::string& description() const;
 
@@ -91,16 +126,30 @@ namespace program_options {
         /// Returns the option name, formatted suitably for usage message. 
         std::string format_name() const;
 
-        /** Return the parameter name and properties, formatted suitably for
+        /** Returns the parameter name and properties, formatted suitably for
             usage message. */
         std::string format_parameter() const;
 
     private:
+    
+        option_description& set_names(const char* name);
 
-        option_description& name(const char* name);
+        /**
+         * a one-character "switch" name - with its prefix,
+         * so that this is either empty or has length 2 (e.g. "-c"
+         */
+        std::string m_short_name;
+
+        /**
+         *  one or more names by which this option may be specified
+         *  on a command-line or in a config file, which are not
+         *  a single-letter switch. The names here are _without_
+         * any prefix.
+         */
+        std::vector<std::string> m_long_names;
+
+        std::string m_description;
 
-        std::string m_short_name, m_long_name, m_description;
-        std::string m_default_value, m_default_parameter;
         // shared_ptr is needed to simplify memory management in
         // copy ctor and destructor.
         shared_ptr<const value_semantic> m_value_semantic;
@@ -141,13 +190,21 @@ namespace program_options {
     */
     class BOOST_PROGRAM_OPTIONS_DECL options_description {
     public:
-
+        static const unsigned m_default_line_length;
+        
         /** Creates the instance. */
-        options_description();
+        options_description(unsigned line_length = m_default_line_length,
+                            unsigned min_description_length = m_default_line_length / 2);
         /** Creates the instance. The 'caption' parameter gives the name of
             this 'options_description' instance. Primarily useful for output.
+            The 'description_length' specifies the number of columns that
+            should be reserved for the description text; if the option text
+            encroaches into this, then the description will start on the next
+            line.
         */
-        options_description(const std::string& caption);
+        options_description(const std::string& caption,
+                            unsigned line_length = m_default_line_length,
+                            unsigned min_description_length = m_default_line_length / 2);
         /** Adds new variable description. Throws duplicate_variable_error if
             either short or long name matches that of already present one. 
         */
@@ -160,6 +217,10 @@ namespace program_options {
         */
         options_description& add(const options_description& desc);
 
+        /** Find the maximum width of the option column, including options 
+            in groups. */
+        unsigned get_option_column_width() const;
+
     public:
         /** Returns an object of implementation-defined type suitable for adding
             options to options_description. The returned object will
@@ -169,32 +230,18 @@ namespace program_options {
         */
         options_description_easy_init add_options();
 
-        /** Count the number of option descriptions with given name. 
-            Returns 0 or 1.
-            The 'name' parameter can be either name of long option, and short
-            option prefixed by '-'.
-        */
-        unsigned count(const std::string& name) const;
-        /** Count the number of descriptions having the given string as
-            prefix. This makes sense only for long options.
-        */
-        unsigned count_approx(const std::string& prefix) const;
-        /** Returns description given a name. 
-            @pre count(name) == 1
-        */
-        const option_description& find(const std::string& name) const;
-        /** Returns description given a prefix. Throws
-            @pre count_approx(name) == 1 
-        */
-        const option_description& find_approx(const std::string& prefix) const;
-        /// Returns all such strings x for which count(x) == 1
-        std::set<std::string> keys() const;
-        /** For each option description stored, contains long name if not empty,
-            if it is empty, short name is returned.
-        */
-        std::set<std::string> primary_keys() const;
-        /// Returns all such long options for which 'prefix' is prefix
-        std::set<std::string> approximations(const std::string& prefix) const;
+        const option_description& find(const std::string& name, 
+                                       bool approx, 
+                                       bool long_ignore_case = false,
+                                       bool short_ignore_case = false) const;
+
+        const option_description* find_nothrow(const std::string& name, 
+                                               bool approx,
+                                               bool long_ignore_case = false,
+                                               bool short_ignore_case = false) const;
+
+
+        const std::vector< shared_ptr<option_description> >& options() const;
 
         /** Produces a human readable output of 'desc', listing options,
             their descriptions and allowed parameters. Other options_description
@@ -202,24 +249,31 @@ namespace program_options {
         friend BOOST_PROGRAM_OPTIONS_DECL std::ostream& operator<<(std::ostream& os, 
                                              const options_description& desc);
 
-        /** Output 'desc' to the specified stream, calling 'f' to output each
+        /** Outputs 'desc' to the specified stream, calling 'f' to output each
             option_description element. */
-        void print(std::ostream& os) const;
+        void print(std::ostream& os, unsigned width = 0) const;
 
     private:
+#if BOOST_WORKAROUND(BOOST_MSVC, BOOST_TESTED_AT(1800))
+        // prevent warning C4512: assignment operator could not be generated
+        options_description& operator=(const options_description&);
+#endif
+
         typedef std::map<std::string, int>::const_iterator name2index_iterator;
         typedef std::pair<name2index_iterator, name2index_iterator> 
             approximation_range;
 
-
-        approximation_range find_approximation(const std::string& prefix) const;
+        //approximation_range find_approximation(const std::string& prefix) const;
 
         std::string m_caption;
+        const unsigned m_line_length;
+        const unsigned m_min_description_length;
+        
         // Data organization is chosen because:
         // - there could be two names for one option
         // - option_add_proxy needs to know the last added option
-        std::vector< shared_ptr<option_description> > options;
-        std::map<std::string, int> name2index;
+        std::vector< shared_ptr<option_description> > m_options;
+
         // Whether the option comes from one of declared groups.
 #if BOOST_WORKAROUND(BOOST_DINKUMWARE_STDLIB, BOOST_TESTED_AT(313))
         // vector<bool> is buggy there, see
@@ -236,8 +290,12 @@ namespace program_options {
     /** Class thrown when duplicate option description is found. */
     class BOOST_PROGRAM_OPTIONS_DECL duplicate_option_error : public error {
     public:
-        duplicate_option_error(const std::string& what) : error(what) {}
+        duplicate_option_error(const std::string& xwhat) : error(xwhat) {}
     };
 }}
 
+#if defined(BOOST_MSVC)
+#   pragma warning (pop)
+#endif
+
 #endif

include/boost/program_options/parsers.hpp

@@ -9,6 +9,7 @@
 
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/option.hpp>
+#include <boost/program_options/detail/cmdline.hpp>
 
 #include <boost/function/function1.hpp>
 
@@ -16,30 +17,46 @@
 #include <vector>
 #include <utility>
 
+#if defined(BOOST_MSVC)
+#   pragma warning (push)
+#   pragma warning (disable:4251) // class 'std::vector<_Ty>' needs to have dll-interface to be used by clients of class 'boost::program_options::basic_parsed_options<wchar_t>'
+#endif
+
 namespace boost { namespace program_options {
 
     class options_description;
     class positional_options_description;
 
 
-    /** Results of parsing an input source. 
-        The primary use of this class is passing information from parsers 
+    /** Results of parsing an input source.
+        The primary use of this class is passing information from parsers
         component to value storage component. This class does not makes
-        much sense itself.        
+        much sense itself.
     */
     template<class charT>
     class basic_parsed_options {
     public:
-        explicit basic_parsed_options(const options_description* description) 
-        : description(description) {}
+        explicit basic_parsed_options(const options_description* xdescription, int options_prefix = 0)
+        : description(xdescription), m_options_prefix(options_prefix) {}
         /** Options found in the source. */
         std::vector< basic_option<charT> > options;
-        /** Options description that was used for parsing. 
-            Parsers should return pointer to the instance of 
+        /** Options description that was used for parsing.
+            Parsers should return pointer to the instance of
             option_description passed to them, and issues of lifetime are
             up to the caller. Can be NULL.
          */
         const options_description* description;
+
+        /** Mainly used for the diagnostic messages in exceptions.
+         *  The canonical option prefix  for the parser which generated these results,
+         *  depending on the settings for basic_command_line_parser::style() or
+         *  cmdline::style(). In order of precedence of command_line_style enums:
+         *      allow_long
+         *      allow_long_disguise
+         *      allow_dash_for_short
+         *      allow_slash_for_short
+        */
+        int m_options_prefix;
     };
 
     /** Specialization of basic_parsed_options which:
@@ -57,7 +74,18 @@ namespace boost { namespace program_options {
 
         /** Stores UTF8 encoded options that were passed to constructor,
             to avoid reverse conversion in some cases. */
-        basic_parsed_options<char> utf8_encoded_options;        
+        basic_parsed_options<char> utf8_encoded_options;
+
+        /** Mainly used for the diagnostic messages in exceptions.
+         *  The canonical option prefix  for the parser which generated these results,
+         *  depending on the settings for basic_command_line_parser::style() or
+         *  cmdline::style(). In order of precedence of command_line_style enums:
+         *      allow_long
+         *      allow_long_disguise
+         *      allow_dash_for_short
+         *      allow_slash_for_short
+        */
+        int m_options_prefix;
     };
 
     typedef basic_parsed_options<char> parsed_options;
@@ -69,37 +97,22 @@ namespace boost { namespace program_options {
 
     typedef function1<std::pair<std::string, std::string>, const std::string&> ext_parser;
 
-    /** Character-type independent command line parser. */
-    class BOOST_PROGRAM_OPTIONS_DECL common_command_line_parser {
-    public:
-        /// Creates the parsers. The arguments must be in internal encoding.
-        common_command_line_parser(const std::vector<std::string>& args);
-        /// Parses the command line and returns parsed options in internal
-        /// encoding.
-        parsed_options run() const;
-    protected:
-        int m_style;
-        const options_description* m_desc;
-        const positional_options_description* m_positional;
-        function1<std::pair<std::string, std::string>, const std::string&> m_ext;
-
-        // Intentionally independent from charT
-        std::vector<std::string> m_args;
-    };
-
     /** Command line parser.
 
         The class allows one to specify all the information needed for parsing
-        and to parser the parse the command line. It is primarily needed to
-        emulate named function parameters -- a regular function with 5
+        and to parse the command line. It is primarily needed to
+        emulate named function parameters \-- a regular function with 5
         parameters will be hard to use and creating overloads with a smaller
-        nuber of parameters will be confusing.
+        number of parameters will be confusing.
 
-        For the most common case, the function parse_command_line is a better 
-        alternative.        
+        For the most common case, the function parse_command_line is a better
+        alternative.
+
+        There are two typedefs \-- command_line_parser and wcommand_line_parser,
+        for charT == char and charT == wchar_t cases.
     */
     template<class charT>
-    class basic_command_line_parser : private common_command_line_parser {
+    class basic_command_line_parser : private detail::cmdline {
     public:
         /** Creates a command line parser for the specified arguments
             list. The 'args' parameter should not include program name.
@@ -107,75 +120,152 @@ namespace boost { namespace program_options {
         basic_command_line_parser(const std::vector<
                                   std::basic_string<charT> >& args);
         /** Creates a command line parser for the specified arguments
-            list. The parameter should be the same as passes to 'main'.
+            list. The parameters should be the same as passed to 'main'.
         */
-        basic_command_line_parser(int argc, charT* argv[]);
+        basic_command_line_parser(int argc, const charT* const argv[]);
 
+        /** Sets options descriptions to use. */
         basic_command_line_parser& options(const options_description& desc);
+        /** Sets positional options description to use. */
         basic_command_line_parser& positional(
             const positional_options_description& desc);
 
+        /** Sets the command line style. */
         basic_command_line_parser& style(int);
+        /** Sets the extra parsers. */
         basic_command_line_parser& extra_parser(ext_parser);
-        
-        basic_parsed_options<charT> run() const;
+
+        /** Parses the options and returns the result of parsing.
+            Throws on error.
+        */
+        basic_parsed_options<charT> run();
+
+        /** Specifies that unregistered options are allowed and should
+            be passed though. For each command like token that looks
+            like an option but does not contain a recognized name, an
+            instance of basic_option<charT> will be added to result,
+            with 'unrecognized' field set to 'true'. It's possible to
+            collect all unrecognized options with the 'collect_unrecognized'
+            funciton.
+        */
+        basic_command_line_parser& allow_unregistered();
+
+        using detail::cmdline::style_parser;
+
+        basic_command_line_parser& extra_style_parser(style_parser s);
+
     private:
+        const options_description* m_desc;
     };
 
     typedef basic_command_line_parser<char> command_line_parser;
     typedef basic_command_line_parser<wchar_t> wcommand_line_parser;
 
     /** Creates instance of 'command_line_parser', passes parameters to it,
-        and returns the result of calling the 'run' method.        
+        and returns the result of calling the 'run' method.
      */
     template<class charT>
     basic_parsed_options<charT>
-    parse_command_line(int argc, charT* argv[],
+    parse_command_line(int argc, const charT* const argv[],
                        const options_description&,
                        int style = 0,
-                       function1<std::pair<std::string, std::string>, 
+                       function1<std::pair<std::string, std::string>,
                                  const std::string&> ext
                        = ext_parser());
 
-    /** Parse a config file. 
+    /** Parse a config file.
+
+        Read from given stream.
     */
     template<class charT>
 #if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
     BOOST_PROGRAM_OPTIONS_DECL
 #endif
     basic_parsed_options<charT>
-    parse_config_file(std::basic_istream<charT>&, const options_description&);
+    parse_config_file(std::basic_istream<charT>&, const options_description&,
+                      bool allow_unregistered = false);
 
-    /** Parse environment. 
+    /** Parse a config file.
+
+        Read from file with the given name. The character type is
+        passed to the file stream.
+    */
+#ifdef BOOST_NO_CXX11_FUNCTION_TEMPLATE_DEFAULT_ARGS
+    template<class charT>
+#else
+    template<class charT = char>
+#endif
+#if ! BOOST_WORKAROUND(__ICL, BOOST_TESTED_AT(700))
+    BOOST_PROGRAM_OPTIONS_DECL
+#endif
+    basic_parsed_options<charT>
+    parse_config_file(const char* filename, const options_description&,
+                      bool allow_unregistered = false);
+
+    /** Controls if the 'collect_unregistered' function should
+        include positional options, or not. */
+    enum collect_unrecognized_mode
+    { include_positional, exclude_positional };
+
+    /** Collects the original tokens for all named options with
+        'unregistered' flag set. If 'mode' is 'include_positional'
+        also collects all positional options.
+        Returns the vector of origianl tokens for all collected
+        options.
+    */
+    template<class charT>
+    std::vector< std::basic_string<charT> >
+    collect_unrecognized(const std::vector< basic_option<charT> >& options,
+                         enum collect_unrecognized_mode mode);
+
+    /** Parse environment.
 
         For each environment variable, the 'name_mapper' function is called to
-        obtain the option name. If it returns empty string, the variable is 
-        ignored. 
+        obtain the option name. If it returns empty string, the variable is
+        ignored.
 
-        This is done since naming of environment variables is typically 
-        different from the naming of command line options.        
+        This is done since naming of environment variables is typically
+        different from the naming of command line options.
     */
     BOOST_PROGRAM_OPTIONS_DECL parsed_options
-    parse_environment(const options_description&, 
+    parse_environment(const options_description&,
                       const function1<std::string, std::string>& name_mapper);
 
     /** Parse environment.
 
         Takes all environment variables which start with 'prefix'. The option
-        name is obtained from variable name by removing the prefix and 
+        name is obtained from variable name by removing the prefix and
         converting the remaining string into lower case.
     */
     BOOST_PROGRAM_OPTIONS_DECL parsed_options
     parse_environment(const options_description&, const std::string& prefix);
 
     /** @overload
-        This function exists to resolve ambiguity between the two above 
+        This function exists to resolve ambiguity between the two above
         functions when second argument is of 'char*' type. There's implicit
         conversion to both function1 and string.
     */
     BOOST_PROGRAM_OPTIONS_DECL parsed_options
     parse_environment(const options_description&, const char* prefix);
 
+    /** Splits a given string to a collection of single strings which
+        can be passed to command_line_parser. The second parameter is
+        used to specify a collection of possible seperator chars used
+        for splitting. The seperator is defaulted to space " ".
+        Splitting is done in a unix style way, with respect to quotes '"'
+        and escape characters '\'
+    */
+    BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string>
+    split_unix(const std::string& cmdline, const std::string& seperator = " \t",
+         const std::string& quote = "'\"", const std::string& escape = "\\");
+
+#ifndef BOOST_NO_STD_WSTRING
+    /** @overload */
+    BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
+    split_unix(const std::wstring& cmdline, const std::wstring& seperator = L" \t",
+         const std::wstring& quote = L"'\"", const std::wstring& escape = L"\\");
+#endif
+
     #ifdef _WIN32
     /** Parses the char* string which is passed to WinMain function on
         windows. This function is provided for convenience, and because it's
@@ -193,10 +283,15 @@ namespace boost { namespace program_options {
     #endif
 #endif
 
+
 }}
 
+#if defined(BOOST_MSVC)
+#   pragma warning (pop)
+#endif
+
 #undef DECL
 
-#include "detail/parsers.hpp"
+#include "boost/program_options/detail/parsers.hpp"
 
 #endif

include/boost/program_options/positional_options.hpp

@@ -11,6 +11,11 @@
 #include <vector>
 #include <string>
 
+#if defined(BOOST_MSVC)
+#   pragma warning (push)
+#   pragma warning (disable:4251) // class 'std::vector<_Ty>' needs to have dll-interface to be used by clients of class 'boost::program_options::positional_options_description'
+#endif
+
 namespace boost { namespace program_options {
 
     /** Describes positional options. 
@@ -37,10 +42,11 @@ namespace boost { namespace program_options {
             No calls to 'add' can be made after call with 'max_value' equal to 
             '-1'.            
         */
-        void add(const char* name, int max_count);
+        positional_options_description&
+        add(const char* name, int max_count);
 
         /** Returns the maximum number of positional options that can
-            be present. Can return numeric_limits<unsigned>::max() to
+            be present. Can return (numeric_limits<unsigned>::max)() to
             indicate unlimited number. */
         unsigned max_total_count() const;
 
@@ -60,5 +66,9 @@ namespace boost { namespace program_options {
 
 }}
 
+#if defined(BOOST_MSVC)
+#   pragma warning (pop)
+#endif
+
 #endif
 

include/boost/program_options/value_semantic.hpp

@@ -13,10 +13,10 @@
 #include <boost/function/function1.hpp>
 #include <boost/lexical_cast.hpp>
 
-
-
 #include <string>
 #include <vector>
+#include <typeinfo>
+#include <limits>
 
 namespace boost { namespace program_options {
 
@@ -30,11 +30,13 @@ namespace boost { namespace program_options {
          */
         virtual std::string name() const = 0;
 
-        /** Returns true if value cannot be specified in source at all.
-            Other methods can still set the value somehow, but
-            user can't affect it.
-        */
-        virtual bool is_zero_tokens() const = 0;
+        /** The minimum number of tokens for this option that
+            should be present on the command line. */
+        virtual unsigned min_tokens() const = 0;
+
+        /** The maximum number of tokens for this option that
+            should be present on the command line. */
+        virtual unsigned max_tokens() const = 0;
 
         /** Returns true if values from different sources should be composed.
             Otherwise, value from the first source is used and values from
@@ -42,12 +44,10 @@ namespace boost { namespace program_options {
         */
         virtual bool is_composing() const = 0;
 
-        /** Returns true if explicit value of an option can be omitted. 
-        */
-        virtual bool is_implicit() const = 0;
+        /** Returns true if value must be given. Non-optional value
 
-        /** Returns true if value can span several token in input source. */
-        virtual bool is_multitoken() const = 0;
+        */
+        virtual bool is_required() const = 0;
         
         /** Parses a group of tokens that specify a value of option.
             Stores the result in 'value_store', using whatever representation
@@ -79,6 +79,13 @@ namespace boost { namespace program_options {
         // Nothing here. Specializations to follow.
     };
 
+    /** Helper conversion class for values that accept ascii
+        strings as input.
+        Overrides the 'parse' method and defines new 'xparse'
+        method taking std::string. Depending on whether input
+        to parse is ascii or UTF8, will pass it to xparse unmodified,
+        or with UTF8->ascii conversion.
+    */
     template<>
     class BOOST_PROGRAM_OPTIONS_DECL 
     value_semantic_codecvt_helper<char> : public value_semantic {
@@ -92,6 +99,13 @@ namespace boost { namespace program_options {
             const = 0;
     };
 
+    /** Helper conversion class for values that accept ascii
+        strings as input.
+        Overrides the 'parse' method and defines new 'xparse'
+        method taking std::wstring. Depending on whether input
+        to parse is ascii or UTF8, will recode input to Unicode, or
+        pass it unmodified.
+    */
     template<>
     class BOOST_PROGRAM_OPTIONS_DECL
     value_semantic_codecvt_helper<wchar_t> : public value_semantic {
@@ -106,6 +120,7 @@ namespace boost { namespace program_options {
             const = 0;
 #endif
     };
+
     /** Class which specifies a simple handling of a value: the value will
         have string type and only one token is allowed. */    
     class BOOST_PROGRAM_OPTIONS_DECL 
@@ -117,10 +132,12 @@ namespace boost { namespace program_options {
 
         std::string name() const;
 
-        bool is_zero_tokens() const { return m_zero_tokens; }
+        unsigned min_tokens() const;
+        unsigned max_tokens() const;
+
         bool is_composing() const { return false; }
-        bool is_implicit() const { return false; }
-        bool is_multitoken() const { return false; }
+
+        bool is_required() const { return false; }
         
         /** If 'value_store' is already initialized, or new_tokens
             has more than one elements, throws. Otherwise, assigns
@@ -139,15 +156,40 @@ namespace boost { namespace program_options {
         bool m_zero_tokens;
     };
 
+#ifndef BOOST_NO_RTTI
+    /** Base class for all option that have a fixed type, and are
+        willing to announce this type to the outside world.
+        Any 'value_semantics' for which you want to find out the
+        type can be dynamic_cast-ed to typed_value_base. If conversion
+        succeeds, the 'type' method can be called.
+    */
+    class typed_value_base 
+    {
+    public:
+        // Returns the type of the value described by this
+        // object.
+        virtual const std::type_info& value_type() const = 0;
+        // Not really needed, since deletion from this
+        // class is silly, but just in case.
+        virtual ~typed_value_base() {}
+    };
+#endif
+
+
     /** Class which handles value of a specific type. */
     template<class T, class charT = char>
-    class typed_value : public value_semantic_codecvt_helper<charT>  {
+    class typed_value : public value_semantic_codecvt_helper<charT>
+#ifndef BOOST_NO_RTTI
+                      , public typed_value_base
+#endif
+    {
     public:
         /** Ctor. The 'store_to' parameter tells where to store
             the value when it's known. The parameter can be NULL. */
         typed_value(T* store_to) 
         : m_store_to(store_to), m_composing(false),
-          m_implicit(false), m_multitoken(false), m_zero_tokens(false)
+          m_implicit(false), m_multitoken(false),
+          m_zero_tokens(false), m_required(false)
         {} 
 
         /** Specifies default value, which will be used
@@ -174,6 +216,42 @@ namespace boost { namespace program_options {
             return this;
         }
 
+        /** Specifies an implicit value, which will be used
+            if the option is given, but without an adjacent value.
+            Using this implies that an explicit value is optional,
+        */
+        typed_value* implicit_value(const T &v)
+        {
+            m_implicit_value = boost::any(v);
+            m_implicit_value_as_text =
+                boost::lexical_cast<std::string>(v);
+            return this;
+        }
+
+        /** Specifies the name used to to the value in help message.  */
+        typed_value* value_name(const std::string& name)
+        {
+            m_value_name = name;
+            return this;
+        }
+
+        /** Specifies an implicit value, which will be used
+            if the option is given, but without an adjacent value.
+            Using this implies that an explicit value is optional, but if
+            given, must be strictly adjacent to the option, i.e.: '-ovalue'
+            or '--option=value'.  Giving '-o' or '--option' will cause the
+            implicit value to be applied.
+            Unlike the above overload, the type 'T' need not provide
+            operator<< for ostream, but textual representation of default
+            value must be provided by the user.
+        */
+        typed_value* implicit_value(const T &v, const std::string& textual)
+        {
+            m_implicit_value = boost::any(v);
+            m_implicit_value_as_text = textual;
+            return this;
+        }
+
         /** Specifies a function to be called when the final value
             is determined. */
         typed_value* notifier(function1<void, const T&> f)
@@ -191,39 +269,63 @@ namespace boost { namespace program_options {
             return this;
         }
 
-        /** Specifies that the value is implicit. */
-        typed_value* implicit()
-        {
-            m_implicit =  true;
-            return this;
-        }
-
-        /** Specifies that the value can span multiple tokens. */
+        /** Specifies that the value can span multiple tokens. 
+        */
         typed_value* multitoken()
         {
             m_multitoken = true;
             return this;
         }
 
+        /** Specifies that no tokens may be provided as the value of
+            this option, which means that only presense of the option
+            is significant. For such option to be useful, either the
+            'validate' function should be specialized, or the 
+            'implicit_value' method should be also used. In most
+            cases, you can use the 'bool_switch' function instead of
+            using this method. */
         typed_value* zero_tokens() 
         {
             m_zero_tokens = true;
             return this;
         }
             
+        /** Specifies that the value must occur. */
+        typed_value* required()
+        {
+            m_required = true;
+            return this;
+        }
 
     public: // value semantic overrides
 
         std::string name() const;
 
-        bool is_zero_tokens() const { return m_zero_tokens; }
         bool is_composing() const { return m_composing; }
-        bool is_implicit() const { return m_implicit; }        
-        bool is_multitoken() const { return m_multitoken; }
 
+        unsigned min_tokens() const
+        {
+            if (m_zero_tokens || !m_implicit_value.empty()) {
+                return 0;
+            } else {
+                return 1;
+            }
+        }
+
+        unsigned max_tokens() const {
+            if (m_multitoken) {
+                return std::numeric_limits<unsigned>::max BOOST_PREVENT_MACRO_SUBSTITUTION();
+            } else if (m_zero_tokens) {
+                return 0;
+            } else {
+                return 1;
+            }
+        }
+
+        bool is_required() const { return m_required; }
 
         /** Creates an instance of the 'validator' class and calls
-            its operator() to perform athe ctual conversion. */
+            its operator() to perform the actual conversion. */
         void xparse(boost::any& value_store, 
                     const std::vector< std::basic_string<charT> >& new_tokens) 
             const;
@@ -246,6 +348,15 @@ namespace boost { namespace program_options {
             when creating *this, stores the value there. Otherwise,
             does nothing. */
         void notify(const boost::any& value_store) const;
+
+    public: // typed_value_base overrides
+        
+#ifndef BOOST_NO_RTTI
+        const std::type_info& value_type() const
+        {
+            return typeid(T);
+        }
+#endif
         
 
     private:
@@ -253,9 +364,12 @@ namespace boost { namespace program_options {
         
         // Default value is stored as boost::any and not
         // as boost::optional to avoid unnecessary instantiations.
+        std::string m_value_name;
         boost::any m_default_value;
         std::string m_default_value_as_text;
-        bool m_composing, m_implicit, m_multitoken, m_zero_tokens;
+        boost::any m_implicit_value;
+        std::string m_implicit_value_as_text;
+        bool m_composing, m_implicit, m_multitoken, m_zero_tokens, m_required;
         boost::function1<void, const T&> m_notifier;
     };
 
@@ -304,7 +418,7 @@ namespace boost { namespace program_options {
 
 }}
 
-#include "detail/value_semantic.hpp"
+#include "boost/program_options/detail/value_semantic.hpp"
 
 #endif
 

include/boost/program_options/variables_map.hpp

@@ -14,6 +14,12 @@
 
 #include <string>
 #include <map>
+#include <set>
+
+#if defined(BOOST_MSVC)
+#   pragma warning (push)
+#   pragma warning (disable:4251) // 'boost::program_options::variable_value::v' : class 'boost::any' needs to have dll-interface to be used by clients of class 'boost::program_options::variable_value
+#endif
 
 namespace boost { namespace program_options {
 
@@ -23,22 +29,50 @@ namespace boost { namespace program_options {
     class value_semantic;
     class variables_map;
 
-    /** Class holding value of option. Contains details about how the 
+    // forward declaration
+
+    /** Stores in 'm' all options that are defined in 'options'.
+        If 'm' already has a non-defaulted value of an option, that value
+        is not changed, even if 'options' specify some value.
+    */
+    BOOST_PROGRAM_OPTIONS_DECL
+    void store(const basic_parsed_options<char>& options, variables_map& m,
+                    bool utf8 = false);
+
+    /** Stores in 'm' all options that are defined in 'options'.
+        If 'm' already has a non-defaulted value of an option, that value
+        is not changed, even if 'options' specify some value.
+        This is wide character variant.
+    */
+    BOOST_PROGRAM_OPTIONS_DECL
+    void store(const basic_parsed_options<wchar_t>& options,
+                    variables_map& m);
+
+
+    /** Runs all 'notify' function for options in 'm'. */
+    BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
+
+    /** Class holding value of option. Contains details about how the
         value is set and allows to conveniently obtain the value.
     */
     class BOOST_PROGRAM_OPTIONS_DECL variable_value {
     public:
         variable_value() : m_defaulted(false) {}
-        variable_value(const boost::any& v, bool defaulted) 
-        : v(v), m_defaulted(defaulted) 
+        variable_value(const boost::any& xv, bool xdefaulted)
+        : v(xv), m_defaulted(xdefaulted)
         {}
 
         /** If stored value if of type T, returns that value. Otherwise,
             throws boost::bad_any_cast exception. */
-        template<class T> const T& as() const;
-
-        /** @overload */
-        template<class T> T& as();
+       template<class T>
+       const T& as() const {
+           return boost::any_cast<const T&>(v);
+       }
+       /** @overload */
+       template<class T>
+       T& as() {
+           return boost::any_cast<T&>(v);
+       }
 
         /// Returns true if no value is stored.
         bool empty() const;
@@ -60,10 +94,11 @@ namespace boost { namespace program_options {
         // be easily accessible, so we need to store semantic here.
         shared_ptr<const value_semantic> m_value_semantic;
 
-        friend void BOOST_PROGRAM_OPTIONS_DECL 
-        store(const basic_parsed_options<char>& options, 
+        friend BOOST_PROGRAM_OPTIONS_DECL
+        void store(const basic_parsed_options<char>& options,
               variables_map& m, bool);
-        friend void BOOST_PROGRAM_OPTIONS_DECL notify(variables_map& m);
+
+        friend class BOOST_PROGRAM_OPTIONS_DECL variables_map;
     };
 
     /** Implements string->string mapping with convenient value casting
@@ -83,11 +118,11 @@ namespace boost { namespace program_options {
                 - otherwise, returns empty value
 
             - if there's defaulted value
-                - if there's next varaible map, which has a non-defauled
+                - if there's next variable map, which has a non-defaulted
                   value, return that
                 - otherwise, return value from *this
 
-            - if there's a non-defauled value, returns it.
+            - if there's a non-defaulted value, returns it.
         */
         const variable_value& operator[](const std::string& name) const;
 
@@ -103,7 +138,11 @@ namespace boost { namespace program_options {
         const abstract_variables_map* m_next;
     };
 
-    /** Concrete variables map which store variables in real map. */
+    /** Concrete variables map which store variables in real map.
+
+        This class is derived from std::map<std::string, variable_value>,
+        so you can use all map operators to examine its content.
+    */
     class BOOST_PROGRAM_OPTIONS_DECL variables_map : public abstract_variables_map,
                                public std::map<std::string, variable_value>
     {
@@ -115,31 +154,32 @@ namespace boost { namespace program_options {
         const variable_value& operator[](const std::string& name) const
         { return abstract_variables_map::operator[](name); }
 
+        // Override to clear some extra fields.
+        void clear();
+
+        void notify();
+
     private:
         /** Implementation of abstract_variables_map::get
             which does 'find' in *this. */
         const variable_value& get(const std::string& name) const;
+
+        /** Names of option with 'final' values \-- which should not
+            be changed by subsequence assignments. */
+        std::set<std::string> m_final;
+
+        friend BOOST_PROGRAM_OPTIONS_DECL
+        void store(const basic_parsed_options<char>& options,
+                          variables_map& xm,
+                          bool utf8);
+
+        /** Names of required options, filled by parser which has
+            access to options_description.
+            The map values are the "canonical" names for each corresponding option.
+            This is useful in creating diagnostic messages when the option is absent. */
+        std::map<std::string, std::string> m_required;
     };
 
-    /** Stores in 'm' all options that are defined in 'options'. 
-        If 'm' already has a non-defaulted value of an option, that value
-        is not changed, even if 'options' specify some value.        
-    */
-    BOOST_PROGRAM_OPTIONS_DECL void store(const basic_parsed_options<char>& options, variables_map& m,
-                    bool utf8 = false);
-
-    /** Stores in 'm' all options that are defined in 'options'. 
-        If 'm' already has a non-defaulted value of an option, that value
-        is not changed, even if 'options' specify some value.        
-        This is wide character variant.
-    */
-    BOOST_PROGRAM_OPTIONS_DECL void store(const basic_parsed_options<wchar_t>& options, 
-                    variables_map& m);
-
-
-    /** Runs all 'notify' function for options in 'm'. */
-    BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map& m);
-
 
     /*
      * Templates/inlines
@@ -171,24 +211,10 @@ namespace boost { namespace program_options {
         return v;
     }
 
-
-    template<class T>
-    const T&
-    variable_value::as() const {
-        const T* r = boost::any_cast<T>(&v);
-        if (!r)
-            throw boost::bad_any_cast();
-        return *r;
-    }
-
-    template<class T>
-    T&
-    variable_value::as() {
-        T* r = boost::any_cast<T>(&v);
-        if (!r)
-            throw boost::bad_any_cast();
-        return *r;
-    }
 }}
 
+#if defined(BOOST_MSVC)
+#   pragma warning (pop)
+#endif
+
 #endif

include/boost/program_options/version.hpp

@@ -15,5 +15,8 @@
 #endif
 #define BOOST_PROGRAM_OPTIONS_VERSION 2
 
+// Signal that implicit options will use values from next
+// token, if available.
+#define BOOST_PROGRAM_OPTIONS_IMPLICIT_VALUE_NEXT_TOKEN 1
 
 #endif

index.html

@@ -4,6 +4,11 @@
 </head>
 <body>
 Automatic redirection failed, please go to
-<a href="../../doc/html/program_options.html">../../doc/html/program_options.html</a>
+<a href="../../doc/html/program_options.html">../../doc/html/program_options.html</a> 
+&nbsp;<hr>
+<p>© Copyright Beman Dawes, 2001</p>
+<p>Distributed under the Boost Software License, Version 1.0. (See accompanying 
+file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy 
+at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
 </body>
-</html>
+</html>

meta/libraries.json

@@ -0,0 +1,15 @@
+{
+    "key": "program_options",
+    "name": "Program Options",
+    "authors": [
+        "Vladimir Prus"
+    ],
+    "description": "The program_options library allows program developers to obtain program options, that is (name, value) pairs from the user, via conventional methods such as command line and config file.",
+    "category": [
+        "IO",
+        "Miscellaneous"
+    ],
+    "maintainers": [
+        "Vladimir Prus <vladimir.prus -at- gmail.com>"
+    ]
+}

src/config_file.cpp

@@ -10,6 +10,7 @@
 #include <boost/program_options/detail/config_file.hpp>
 #include <boost/program_options/errors.hpp>
 #include <boost/program_options/detail/convert.hpp>
+#include <boost/throw_exception.hpp>
 
 #include <iostream>
 #include <fstream>
@@ -20,8 +21,10 @@ namespace boost { namespace program_options { namespace detail {
     using namespace std;
 
     common_config_file_iterator::common_config_file_iterator(
-        const std::set<std::string>& allowed_options)
-    : allowed_options(allowed_options)
+        const std::set<std::string>& allowed_options,
+        bool allow_unregistered)
+    : allowed_options(allowed_options),
+      m_allow_unregistered(allow_unregistered)
     {
         for(std::set<std::string>::const_iterator i = allowed_options.begin();
             i != allowed_options.end(); 
@@ -54,7 +57,9 @@ namespace boost { namespace program_options { namespace detail {
                     bad_prefixes = true;
             }
             if (bad_prefixes)
-                throw error("bad prefixes");
+                boost::throw_exception(error("options '" + string(name) + "' and '" +
+                                             *i + "*' will both match the same "
+                                             "arguments from the configuration file"));
             allowed_prefixes.insert(s);
         }
     }
@@ -99,20 +104,22 @@ namespace boost { namespace program_options { namespace detail {
                     string name = m_prefix + trim_ws(s.substr(0, n));
                     string value = trim_ws(s.substr(n+1));
 
-                    if (!allowed_option(name))
-                        throw unknown_option(name);
-                                        
-                    if (value.empty())
-                        throw invalid_syntax(s, "no value given");
-                    
+                    bool registered = allowed_option(name);
+                    if (!registered && !m_allow_unregistered)
+                        boost::throw_exception(unknown_option(name));
+
                     found = true;
                     this->value().string_key = name;
                     this->value().value.clear();
                     this->value().value.push_back(value);
+                    this->value().unregistered = !registered;
+                    this->value().original_tokens.clear();
+                    this->value().original_tokens.push_back(name);
+                    this->value().original_tokens.push_back(value);
                     break;
 
                 } else {
-                    throw invalid_syntax(s, "unrecognized line");
+                    boost::throw_exception(invalid_config_file_syntax(s, invalid_syntax::unrecognized_line));
                 }
             }
         }
@@ -136,9 +143,8 @@ namespace boost { namespace program_options { namespace detail {
         return false;
     }
 
-// On Metrowerks, the function is defined inline.
-
-#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303))
+#if BOOST_WORKAROUND(__COMO_VERSION__, BOOST_TESTED_AT(4303)) || \
+        (defined(__sgi) && BOOST_WORKAROUND(_COMPILER_VERSION, BOOST_TESTED_AT(741)))
     template<>
     bool
     basic_config_file_iterator<wchar_t>::getline(std::string& s)

src/convert.cpp

@@ -17,10 +17,12 @@
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/detail/convert.hpp>
 #include <boost/program_options/detail/utf8_codecvt_facet.hpp>
+#include <boost/throw_exception.hpp>
 
-#include <boost/bind.hpp>
+#include <boost/bind/bind.hpp>
 
 using namespace std;
+using namespace boost::placeholders;
 
 namespace boost { namespace detail {
 
@@ -42,7 +44,7 @@ namespace boost { namespace detail {
     {
         std::basic_string<ToChar> result;
         
-        std::mbstate_t state = {0};
+        std::mbstate_t state = std::mbstate_t();
 
         const FromChar* from = s.data();
         const FromChar* from_end = s.data() + s.size();
@@ -62,14 +64,16 @@ namespace boost { namespace detail {
                 fun(state, from, from_end, from, buffer, to_end, to_next);
             
             if (r == std::codecvt_base::error)
-                throw std::logic_error("character conversion failed");
+                boost::throw_exception(
+                    std::logic_error("character conversion failed"));
             // 'partial' is not an error, it just means not all source
             // characters were converted. However, we need to check that at
             // least one new target character was produced. If not, it means
             // the source data is incomplete, and since we don't have extra
             // data to add to source, it's error.
             if (to_next == buffer)
-                throw std::logic_error("character conversion failed");
+                boost::throw_exception(
+                    std::logic_error("character conversion failed"));
             
             // Add converted characters
             result.append(buffer, to_next);
@@ -106,7 +110,7 @@ namespace boost {
 
 
     namespace {
-        boost::program_options::detail::utf8_codecvt_facet<wchar_t, char> 
+        boost::program_options::detail::utf8_codecvt_facet
             utf8_facet;
     }
     

src/options_description.cpp

@@ -1,4 +1,5 @@
 // Copyright Vladimir Prus 2002-2004.
+// Copyright Bertolt Mildner 2004.
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -7,74 +8,214 @@
 #define BOOST_PROGRAM_OPTIONS_SOURCE
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/options_description.hpp>
-// FIXME: this is only to get multiple_occureces class
+// FIXME: this is only to get multiple_occurrences class
 // should move that to a separate headers.
 #include <boost/program_options/parsers.hpp>
 
-#include <boost/lexical_cast.hpp>
 
+#include <boost/lexical_cast.hpp>
+#include <boost/tokenizer.hpp>
 #include <boost/detail/workaround.hpp>
+#include <boost/throw_exception.hpp>
 
 #include <cassert>
 #include <climits>
 #include <cstring>
 #include <cstdarg>
 #include <sstream>
+#include <iterator>
 using namespace std;
 
 namespace boost { namespace program_options {
 
+   namespace {
+
+       template< class charT >
+       std::basic_string< charT >  tolower_(const std::basic_string< charT >& str)
+       {
+           std::basic_string< charT > result;
+           for (typename std::basic_string< charT >::size_type i = 0; i < str.size(); ++i)
+           {
+               result.append(1, static_cast< charT >(std::tolower(str[i])));
+           }   
+           return result;
+       }
+
+    }  // unnamed namespace
+
+
     option_description::option_description()
     {
     }
     
     option_description::
-    option_description(const char* name,
+    option_description(const char* names,
                        const value_semantic* s)
     : m_value_semantic(s)
     {
-        this->name(name);
+        this->set_names(names);
     }
                                            
 
     option_description::
-    option_description(const char* name,
+    option_description(const char* names,
                        const value_semantic* s,
                        const char* description)
     : m_description(description), m_value_semantic(s)
     {
-        this->name(name);
+        this->set_names(names);
     }
 
     option_description::~option_description()
     {
     }
 
-    option_description&
-    option_description::name(const char* _name)
+    option_description::match_result
+    option_description::match(const std::string& option, 
+                              bool approx, 
+                              bool long_ignore_case,
+                              bool short_ignore_case) const
     {
-        std::string name(_name);
-        string::size_type n = name.find(',');
-        if (n != string::npos) {
-            assert(n == name.size()-2);
-            m_long_name = name.substr(0, n);
-            m_short_name = name.substr(n+1,1);
-        } else {
-            m_long_name = name;
+        match_result result = no_match;        
+        std::string local_option = (long_ignore_case ? tolower_(option) : option);
+        
+        for(std::vector<std::string>::const_iterator it(m_long_names.begin()); it != m_long_names.end(); it++)
+        {
+            std::string local_long_name((long_ignore_case ? tolower_(*it) : *it));
+
+            if (!local_long_name.empty()) {
+
+
+                if ((result == no_match) && (*local_long_name.rbegin() == '*'))
+                {
+                    // The name ends with '*'. Any specified name with the given
+                    // prefix is OK.
+                    if (local_option.find(local_long_name.substr(0, local_long_name.length()-1))
+                        == 0)
+                        result = approximate_match;
+                }
+
+                if (local_long_name == local_option)
+                {
+                    result = full_match;
+                    break;
+                }
+                else if (approx)
+                {
+                    if (local_long_name.find(local_option) == 0)
+                    {
+                        result = approximate_match;
+                    }
+                }
+            }
+
         }
-        return *this;
+
+        if (result != full_match)
+        {
+            std::string local_short_name(short_ignore_case ? tolower_(m_short_name) : m_short_name);
+
+            if (local_short_name == local_option)
+            {
+                result = full_match;
+            }
+        }
+
+        return result;        
     }
 
-    const std::string&
-    option_description::short_name() const
+    const std::string& 
+    option_description::key(const std::string& option) const
     {
-        return m_short_name;
+        // We make the arbitrary choise of using the first long
+        // name as the key, regardless of anything else
+        if (!m_long_names.empty()) {
+            const std::string& first_long_name = *m_long_names.begin();
+            if (first_long_name.find('*') != string::npos)
+                // The '*' character means we're long_name
+                // matches only part of the input. So, returning
+                // long name will remove some of the information,
+                // and we have to return the option as specified
+                // in the source.
+                return option;
+            else
+                return first_long_name;
+        }
+        else
+            return m_short_name;
     }
 
+    std::string 
+    option_description::canonical_display_name(int prefix_style) const
+    {
+        // We prefer the first long name over any others
+        if (!m_long_names.empty())
+        {
+            if (prefix_style == command_line_style::allow_long)
+                return "--" + *m_long_names.begin();
+            if (prefix_style == command_line_style::allow_long_disguise)
+                return "-" + *m_long_names.begin();
+        }
+        // sanity check: m_short_name[0] should be '-' or '/'
+        if (m_short_name.length() == 2)
+        {
+            if (prefix_style == command_line_style::allow_slash_for_short)
+                return string("/") + m_short_name[1];
+            if (prefix_style == command_line_style::allow_dash_for_short)
+                return string("-") + m_short_name[1];
+        }
+        if (!m_long_names.empty())
+            return *m_long_names.begin();
+        else
+            return m_short_name;
+    }
+
+
     const std::string&
     option_description::long_name() const
     {
-        return m_long_name;
+        static std::string empty_string("");
+        return m_long_names.empty() ? empty_string : *m_long_names.begin();
+    }
+
+    const std::pair<const std::string*, std::size_t>
+    option_description::long_names() const
+    {
+        // reinterpret_cast is to please msvc 10.
+        return (m_long_names.empty())
+            ? std::pair<const std::string*, size_t>(reinterpret_cast<const std::string*>(0), 0 )
+            : std::pair<const std::string*, size_t>( &(*m_long_names.begin()), m_long_names.size());
+    }
+
+    option_description&
+    option_description::set_names(const char* _names)
+    {
+        m_long_names.clear();
+        std::istringstream iss(_names);
+        std::string name;
+
+        while(std::getline(iss, name, ',')) {
+            m_long_names.push_back(name);
+        }
+        assert(!m_long_names.empty() && "No option names were specified");
+
+        bool try_interpreting_last_name_as_a_switch = m_long_names.size() > 1;
+        if (try_interpreting_last_name_as_a_switch) {
+            const std::string& last_name = *m_long_names.rbegin();
+            if (last_name.length() == 1) {
+                m_short_name = '-' + last_name;
+                m_long_names.pop_back();
+                // The following caters to the (valid) input of ",c" for some
+                // character c, where the caller only wants this option to have
+                // a short name.
+                if (m_long_names.size() == 1 && (*m_long_names.begin()).empty()) {
+                    m_long_names.clear();
+                }
+            }
+        }
+        // We could theoretically also ensure no remaining long names
+        // are empty, or that none of them have length 1
+        return *this;
     }
 
     const std::string&
@@ -92,17 +233,20 @@ namespace boost { namespace program_options {
     std::string 
     option_description::format_name() const
     {
-        if (!short_name().empty())
-            return string("-").append(short_name()).append(" [ --").
-            append(long_name()).append(" ]");
-        else
-            return string("--").append(long_name());
+        if (!m_short_name.empty())
+        {
+            return m_long_names.empty()
+                ? m_short_name 
+                : string(m_short_name).append(" [ --").
+                  append(*m_long_names.begin()).append(" ]");
+        }
+        return string("--").append(*m_long_names.begin());
     }
 
     std::string 
     option_description::format_parameter() const
     {
-        if (!m_value_semantic->is_zero_tokens())
+        if (m_value_semantic->max_tokens() != 0)
             return m_value_semantic->name();
         else
             return "";
@@ -150,30 +294,32 @@ namespace boost { namespace program_options {
         return *this;
     }
 
-    options_description::options_description()
-    {}
+    const unsigned options_description::m_default_line_length = 80;
 
-    options_description::options_description(const string& caption)
+    options_description::options_description(unsigned line_length,
+                                             unsigned min_description_length)
+    : m_line_length(line_length)
+    , m_min_description_length(min_description_length)
+    {
+        // we require a space between the option and description parts, so add 1.
+        assert(m_min_description_length < m_line_length - 1);    
+    }
+
+    options_description::options_description(const std::string& caption,
+                                             unsigned line_length,
+                                             unsigned min_description_length)
     : m_caption(caption)
-    {}
-
+    , m_line_length(line_length)
+    , m_min_description_length(min_description_length)
+    {
+        // we require a space between the option and description parts, so add 1.
+        assert(m_min_description_length < m_line_length - 1);
+    }
+    
     void
     options_description::add(shared_ptr<option_description> desc)
     {
-        const string& s = desc->short_name();
-        const string& l = desc->long_name();
-        assert(!s.empty() || !l.empty());
-        if (!s.empty())
-            if (name2index.count("-" + s) != 0)
-                throw duplicate_option_error("Short name '" + s + "' is already present");
-            else
-                name2index["-" + s] = options.size();
-        if (!l.empty())
-            if (name2index.count(s) != 0)
-                throw duplicate_option_error("Long name '" + s + "' is already present");
-            else
-                name2index[l] = options.size();
-        options.push_back(desc);
+        m_options.push_back(desc);
         belong_to_group.push_back(false);
     }
 
@@ -183,8 +329,8 @@ namespace boost { namespace program_options {
         shared_ptr<options_description> d(new options_description(desc));
         groups.push_back(d);
 
-        for (size_t i = 0; i < desc.options.size(); ++i) {
-            add(desc.options[i]);
+        for (size_t i = 0; i < desc.m_options.size(); ++i) {
+            add(desc.m_options[i]);
             belong_to_group.back() = true;
         }
 
@@ -197,76 +343,76 @@ namespace boost { namespace program_options {
         return options_description_easy_init(this);
     }
 
-    unsigned
-    options_description::count(const std::string& name) const
-    {
-        return name2index.count(name);
-    }
-
-    unsigned
-    options_description::count_approx(const std::string& prefix) const
-    {
-        approximation_range er = find_approximation(prefix);
-        return distance(er.first, er.second);
-    }
-
     const option_description&
-    options_description::find(const std::string& name) const
+    options_description::find(const std::string& name, 
+                              bool approx,
+                              bool long_ignore_case,
+                              bool short_ignore_case) const
     {
-        assert(this->count(name) != 0);
-        return *options[name2index.find(name)->second];
+        const option_description* d = find_nothrow(name, approx, 
+                                       long_ignore_case, short_ignore_case);
+        if (!d)
+            boost::throw_exception(unknown_option());
+        return *d;
     }
 
-    const option_description&
-    options_description::find_approx(const std::string& prefix) const
+    const std::vector< shared_ptr<option_description> >& 
+    options_description::options() const
     {
-        approximation_range er = find_approximation(prefix);
-        assert(distance(er.first, er.second) == 1);
-        return *options[er.first->second];
+        return m_options;
     }
 
-    std::set<std::string>
-    options_description::keys() const
+    const option_description*
+    options_description::find_nothrow(const std::string& name, 
+                                      bool approx,
+                                      bool long_ignore_case,
+                                      bool short_ignore_case) const
     {
-        set<string> result;
-        for (map<string, int>::const_iterator i = name2index.begin();
-             i != name2index.end();
-             ++i)
-            result.insert(i->first);
-        return result;
-    }
+        shared_ptr<option_description> found;
+        bool had_full_match = false;
+        vector<string> approximate_matches;
+        vector<string> full_matches;
+        
+        // We use linear search because matching specified option
+        // name with the declared option name need to take care about
+        // case sensitivity and trailing '*' and so we can't use simple map.
+        for(unsigned i = 0; i < m_options.size(); ++i)
+        {
+            option_description::match_result r = 
+                m_options[i]->match(name, approx, long_ignore_case, short_ignore_case);
 
-    std::set<std::string>
-    options_description::primary_keys() const
-    {
-        set<string> result;
-        for (size_t i = 0; i < options.size(); ++i)
-            if (options[i]->long_name().empty())
-                result.insert("-" + options[i]->short_name());
-            else
-                result.insert(options[i]->long_name());
-        return result;
-    }
+            if (r == option_description::no_match)
+                continue;
 
-    std::set<std::string>
-    options_description::approximations(const std::string& prefix) const
-    {
-        approximation_range er = find_approximation(prefix);
-        set<string> result;
-        for (name2index_iterator i = er.first; i != er.second; ++i)
-            result.insert(i->first);
-        return result;
-    }
+            if (r == option_description::full_match)
+            {                
+                full_matches.push_back(m_options[i]->key(name));
+                found = m_options[i];
+                had_full_match = true;
+            } 
+            else 
+            {                        
+                // FIXME: the use of 'key' here might not
+                // be the best approach.
+                approximate_matches.push_back(m_options[i]->key(name));
+                if (!had_full_match)
+                    found = m_options[i];
+            }
+        }
+        if (full_matches.size() > 1) 
+            boost::throw_exception(ambiguous_option(full_matches));
+        
+        // If we have a full match, and an approximate match,
+        // ignore approximate match instead of reporting error.
+        // Say, if we have options "all" and "all-chroots", then
+        // "--all" on the command line should select the first one,
+        // without ambiguity.
+        if (full_matches.empty() && approximate_matches.size() > 1)
+            boost::throw_exception(ambiguous_option(approximate_matches));
 
-    options_description::approximation_range
-    options_description::find_approximation(const std::string& prefix) const
-    {
-        name2index_iterator b = name2index.lower_bound(prefix);
-        name2index_iterator e = name2index.upper_bound(prefix + char(CHAR_MAX));
-        return make_pair(b, e);
+        return found.get();
     }
 
-
     BOOST_PROGRAM_OPTIONS_DECL
     std::ostream& operator<<(std::ostream& os, const options_description& desc)
     {
@@ -275,57 +421,278 @@ namespace boost { namespace program_options {
     }
 
     namespace {
+
+        /* Given a string 'par', that contains no newline characters
+           outputs it to 'os' with wordwrapping, that is, as several
+           line.
+
+           Each output line starts with 'indent' space characters, 
+           following by characters from 'par'. The total length of
+           line is no longer than 'line_length'.
+                                      
+        */
+        void format_paragraph(std::ostream& os,
+                              std::string par,
+                              unsigned indent,
+                              unsigned line_length)
+        {                    
+            // Through reminder of this function, 'line_length' will
+            // be the length available for characters, not including
+            // indent.
+            assert(indent < line_length);
+            line_length -= indent;
+
+            // index of tab (if present) is used as additional indent relative
+            // to first_column_width if paragrapth is spanned over multiple
+            // lines if tab is not on first line it is ignored
+            string::size_type par_indent = par.find('\t');
+
+            if (par_indent == string::npos)
+            {
+                par_indent = 0;
+            }
+            else
+            {
+                // only one tab per paragraph allowed
+                if (count(par.begin(), par.end(), '\t') > 1)
+                {
+                    boost::throw_exception(program_options::error(
+                        "Only one tab per paragraph is allowed in the options description"));
+                }
+          
+                // erase tab from string
+                par.erase(par_indent, 1);
+
+                // this assert may fail due to user error or 
+                // environment conditions!
+                assert(par_indent < line_length);
+
+                // ignore tab if not on first line
+                if (par_indent >= line_length)
+                {
+                    par_indent = 0;
+                }            
+            }
+          
+            if (par.size() < line_length)
+            {
+                os << par;
+            }
+            else
+            {
+                string::const_iterator       line_begin = par.begin();
+                const string::const_iterator par_end = par.end();
+
+                bool first_line = true; // of current paragraph!        
+            
+                while (line_begin < par_end)  // paragraph lines
+                {
+                    if (!first_line)
+                    {
+                        // If line starts with space, but second character
+                        // is not space, remove the leading space.
+                        // We don't remove double spaces because those
+                        // might be intentianal.
+                        if ((*line_begin == ' ') &&
+                            ((line_begin + 1 < par_end) &&
+                             (*(line_begin + 1) != ' ')))
+                        {
+                            line_begin += 1;  // line_begin != line_end
+                        }
+                    }
+
+                    // Take care to never increment the iterator past
+                    // the end, since MSVC 8.0 (brokenly), assumes that
+                    // doing that, even if no access happens, is a bug.
+                    unsigned remaining = static_cast<unsigned>(std::distance(line_begin, par_end));
+                    string::const_iterator line_end = line_begin + 
+                        ((remaining < line_length) ? remaining : line_length);
+            
+                    // prevent chopped words
+                    // Is line_end between two non-space characters?
+                    if ((*(line_end - 1) != ' ') &&
+                        ((line_end < par_end) && (*line_end != ' ')))
+                    {
+                        // find last ' ' in the second half of the current paragraph line
+                        string::const_iterator last_space =
+                            find(reverse_iterator<string::const_iterator>(line_end),
+                                 reverse_iterator<string::const_iterator>(line_begin),
+                                 ' ')
+                            .base();
+                
+                        if (last_space != line_begin)
+                        {                 
+                            // is last_space within the second half ot the 
+                            // current line
+                            if (static_cast<unsigned>(std::distance(last_space, line_end)) < 
+                                (line_length / 2))
+                            {
+                                line_end = last_space;
+                            }
+                        }                                                
+                    } // prevent chopped words
+             
+                    // write line to stream
+                    copy(line_begin, line_end, ostream_iterator<char>(os));
+              
+                    if (first_line)
+                    {
+                        indent += static_cast<unsigned>(par_indent);
+                        line_length -= static_cast<unsigned>(par_indent); // there's less to work with now
+                        first_line = false;
+                    }
+
+                    // more lines to follow?
+                    if (line_end != par_end)
+                    {
+                        os << '\n';
+                
+                        for(unsigned pad = indent; pad > 0; --pad)
+                        {
+                            os.put(' ');
+                        }                                                        
+                    }
+              
+                    // next line starts after of this line
+                    line_begin = line_end;              
+                } // paragraph lines
+            }          
+        }                              
+        
+        void format_description(std::ostream& os,
+                                const std::string& desc, 
+                                unsigned first_column_width,
+                                unsigned line_length)
+        {
+            // we need to use one char less per line to work correctly if actual
+            // console has longer lines
+            assert(line_length > 1);
+            if (line_length > 1)
+            {
+                --line_length;
+            }
+
+            // line_length must be larger than first_column_width
+            // this assert may fail due to user error or environment conditions!
+            assert(line_length > first_column_width);
+
+            // Note: can't use 'tokenizer' as name of typedef -- borland
+            // will consider uses of 'tokenizer' below as uses of
+            // boost::tokenizer, not typedef.
+            typedef boost::tokenizer<boost::char_separator<char> > tok;
+          
+            tok paragraphs(
+                desc,
+                char_separator<char>("\n", "", boost::keep_empty_tokens));
+          
+            tok::const_iterator       par_iter = paragraphs.begin();                
+            const tok::const_iterator par_end = paragraphs.end();
+
+            while (par_iter != par_end)  // paragraphs
+            {
+                format_paragraph(os, *par_iter, first_column_width, 
+                                 line_length);
+            
+                ++par_iter;
+            
+                // prepair next line if any
+                if (par_iter != par_end)
+                {
+                    os << '\n';
+              
+                    for(unsigned pad = first_column_width; pad > 0; --pad)
+                    {
+                        os.put(' ');
+                    }                    
+                }            
+            }  // paragraphs
+        }
+    
         void format_one(std::ostream& os, const option_description& opt, 
-                        unsigned first_column_width)
+                        unsigned first_column_width, unsigned line_length)
         {
             stringstream ss;
             ss << "  " << opt.format_name() << ' ' << opt.format_parameter();
             
             // Don't use ss.rdbuf() since g++ 2.96 is buggy on it.
             os << ss.str();
-            
-            if (!opt.description().empty()) {
-                
-                for(int pad = first_column_width - ss.str().size(); pad > 0; --pad) {
-                    os.put(' ');
+
+            if (!opt.description().empty())
+            {
+                if (ss.str().size() >= first_column_width)
+                {
+                   os.put('\n'); // first column is too long, lets put description in new line
+                   for (unsigned pad = first_column_width; pad > 0; --pad)
+                   {
+                      os.put(' ');
+                   }
+                } else {
+                   for(unsigned pad = first_column_width - static_cast<unsigned>(ss.str().size()); pad > 0; --pad)
+                   {
+                      os.put(' ');
+                   }
                 }
-                os << " : " << opt.description();
+            
+                format_description(os, opt.description(),
+                                   first_column_width, line_length);
             }
         }
     }
 
+    unsigned                                                                    
+    options_description::get_option_column_width() const                                
+    {
+        /* Find the maximum width of the option column */
+        unsigned width(23);
+        unsigned i; // vc6 has broken for loop scoping
+        for (i = 0; i < m_options.size(); ++i)
+        {
+            const option_description& opt = *m_options[i];
+            stringstream ss;
+            ss << "  " << opt.format_name() << ' ' << opt.format_parameter();
+            width = (max)(width, static_cast<unsigned>(ss.str().size()));            
+        }
+
+        /* Get width of groups as well*/
+        for (unsigned j = 0; j < groups.size(); ++j)                            
+            width = max(width, groups[j]->get_option_column_width());
+
+        /* this is the column were description should start, if first
+           column is longer, we go to a new line */
+        const unsigned start_of_description_column = m_line_length - m_min_description_length;
+
+        width = (min)(width, start_of_description_column-1);
+        
+        /* add an additional space to improve readability */
+        ++width;
+        return width;                                                       
+    }
+
     void 
-    options_description::print(std::ostream& os) const
+    options_description::print(std::ostream& os, unsigned width) const
     {
         if (!m_caption.empty())
             os << m_caption << ":\n";
 
-        /* Find the maximum width of the option column */
-        unsigned width(24);
-        unsigned i; // vc6 has broken for loop scoping
-        for (i = 0; i < options.size(); ++i)
-        {
-            const option_description& opt = *options[i];
-            stringstream ss;
-            ss << "  " << opt.format_name() << ' ' << opt.format_parameter();
-            width = max(width, static_cast<unsigned>(ss.str().size()));            
-        }
+        if (!width)
+            width = get_option_column_width();
 
         /* The options formatting style is stolen from Subversion. */
-        for (i = 0; i < options.size(); ++i)
+        for (unsigned i = 0; i < m_options.size(); ++i)
         {
             if (belong_to_group[i])
                 continue;
 
-            const option_description& opt = *options[i];
+            const option_description& opt = *m_options[i];
 
-            format_one(os, opt, width);
+            format_one(os, opt, width, m_line_length);
 
             os << "\n";
         }
 
         for (unsigned j = 0; j < groups.size(); ++j) {            
-            os << "\n" << *groups[j];
+            os << "\n";
+            groups[j]->print(os, width);
         }
     }
 

src/parsers.cpp

@@ -16,8 +16,11 @@
 #include <boost/program_options/environment_iterator.hpp>
 #include <boost/program_options/detail/convert.hpp>
 
-#include <boost/bind.hpp>
+#include <boost/bind/bind.hpp>
+#include <boost/throw_exception.hpp>
 
+#include <cctype>
+#include <fstream>
 
 #if !defined(__GNUC__) || __GNUC__ < 3
 #include <iostream>
@@ -42,7 +45,10 @@
 // See: http://article.gmane.org/gmane.comp.lib.boost.devel/103843
 // See: http://lists.gnu.org/archive/html/bug-guile/2004-01/msg00013.html
 #if defined(__APPLE__) && defined(__DYNAMIC__)
-#include <crt_externs.h>
+// The proper include for this is crt_externs.h, however it's not
+// available on iOS. The right replacement is not known. See
+// https://svn.boost.org/trac/boost/ticket/5053
+extern "C" { extern char ***_NSGetEnviron(void); }
 #define environ (*_NSGetEnviron()) 
 #else
 #if defined(__MWERKS__)
@@ -55,6 +61,7 @@ extern char** environ;
 #endif
 
 using namespace std;
+using namespace boost::placeholders;
 
 namespace boost { namespace program_options {
 
@@ -65,10 +72,16 @@ namespace boost { namespace program_options {
             woption result;
             result.string_key = opt.string_key;
             result.position_key = opt.position_key;
+            result.unregistered = opt.unregistered;
             
             std::transform(opt.value.begin(), opt.value.end(),
                            back_inserter(result.value),
-                           bind(from_utf8, _1));
+                           boost::bind(from_utf8, _1));
+
+            std::transform(opt.original_tokens.begin(), 
+                           opt.original_tokens.end(),
+                           back_inserter(result.original_tokens),
+                           boost::bind(from_utf8, _1));
             return result;
         }
     }
@@ -76,125 +89,38 @@ namespace boost { namespace program_options {
     basic_parsed_options<wchar_t>
     ::basic_parsed_options(const parsed_options& po)
     : description(po.description),
-      utf8_encoded_options(po)
+      utf8_encoded_options(po),
+      m_options_prefix(po.m_options_prefix)
     {
         for (unsigned i = 0; i < po.options.size(); ++i)
             options.push_back(woption_from_option(po.options[i]));
     }
 #endif
 
-    namespace detail
-    {
-        void
-        parse_command_line(cmdline& cmd, parsed_options& result);
-    }
-
-    common_command_line_parser::
-    common_command_line_parser(const std::vector<std::string>& args)
-    : m_style(0), m_desc(0), m_positional(0), m_args(args)
-    {}
-
-    parsed_options
-    common_command_line_parser::run() const
-    {
-        parsed_options result(m_desc);
-        detail::cmdline cmd(m_args, m_style);
-        cmd.set_additional_parser(m_ext);
-
-        if (m_desc) {
-            set<string> keys = m_desc->primary_keys();
-            for (set<string>::iterator i = keys.begin(); i != keys.end(); ++i) {
-                const option_description& d = m_desc->find(*i);
-                char s = d.short_name().empty() ? '\0' : d.short_name()[0];
-
-                shared_ptr<const value_semantic> vs = d.semantic();
-                char flags;
-                if (vs->is_zero_tokens())
-                    flags = '|';
-                else
-                    if (vs->is_implicit()) 
-                        if (vs->is_multitoken())
-                            flags = '*';
-                        else
-                            flags = '?';
-                    else if (vs->is_multitoken())
-                        flags = '+';
-                    else flags = ':';
-
-                cmd.add_option(d.long_name(), s, flags, 1);
-            }
-        }
-
-        detail::parse_command_line(cmd, result);
-
-        if (m_positional)
-        {
-            unsigned position = 0;
-            for (unsigned i = 0; i < result.options.size(); ++i) {
-                option& opt = result.options[i];
-                if (opt.position_key != -1) {
-                    if (position >= m_positional->max_total_count())
-                    {
-                        throw too_many_positional_options_error(
-                            "too many positional options");
-                    }
-                    opt.string_key = m_positional->name_for_position(position);
-                    ++position;
-                }
-            }
-        }
-
-        return result;        
-    }
-
-
-    namespace detail {
-        void
-        parse_command_line(cmdline& cmd, parsed_options& result)
-        {
-            int position(0);
-            
-            while(++cmd) {
-                
-                option n;
-                
-                if (cmd.at_option()) {
-                    if (*cmd.option_name().rbegin() != '*') {
-                        n.string_key = cmd.option_name();
-                    }
-                    else {
-                        n.string_key = cmd.raw_option_name();
-                    }
-                    n.value = cmd.option_values();
-                } else {
-                    n.position_key = position++;
-                    n.value.clear();
-                    n.value.push_back(cmd.argument());
-                }
-                result.options.push_back(n);
-            }
-        }
-    }
-
     template<class charT>
     basic_parsed_options<charT>
     parse_config_file(std::basic_istream<charT>& is, 
-                      const options_description& desc)
+                      const options_description& desc,
+                      bool allow_unregistered)
     {    
         set<string> allowed_options;
-        set<string> pm = desc.primary_keys();
-        for (set<string>::iterator i = pm.begin(); i != pm.end(); ++i) {
-            const option_description& d = desc.find(*i);
+
+        const vector<shared_ptr<option_description> >& options = desc.options();
+        for (unsigned i = 0; i < options.size(); ++i)
+        {
+            const option_description& d = *options[i];
 
             if (d.long_name().empty())
-                throw error("long name required for config file");
+                boost::throw_exception(
+                    error("abbreviated option names are not permitted in options configuration files"));
 
             allowed_options.insert(d.long_name());
         }
 
         // Parser return char strings
         parsed_options result(&desc);        
-        copy(detail::basic_config_file_iterator<charT>(is, allowed_options), 
+        copy(detail::basic_config_file_iterator<charT>(
+                 is, allowed_options, allow_unregistered), 
              detail::basic_config_file_iterator<charT>(), 
              back_inserter(result.options));
         // Convert char strings into desired type.
@@ -204,14 +130,46 @@ namespace boost { namespace program_options {
     template
     BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<char>
     parse_config_file(std::basic_istream<char>& is, 
-                      const options_description& desc);
+                      const options_description& desc,
+                      bool allow_unregistered);
 
 #ifndef BOOST_NO_STD_WSTRING
     template
     BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t>
     parse_config_file(std::basic_istream<wchar_t>& is, 
-                      const options_description& desc);
+                      const options_description& desc,
+                      bool allow_unregistered);
 #endif
+
+    template<class charT>
+    basic_parsed_options<charT>
+    parse_config_file(const char* filename, 
+                      const options_description& desc,
+                      bool allow_unregistered)
+    { 
+        // Parser return char strings
+        std::basic_ifstream< charT > strm(filename);
+        if (!strm) 
+        {
+            boost::throw_exception(reading_file(filename));
+        }
+        return parse_config_file(strm, desc, allow_unregistered);
+    }
+
+    template
+    BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<char>
+    parse_config_file(const char* filename, 
+                      const options_description& desc,
+                      bool allow_unregistered);
+
+#ifndef BOOST_NO_STD_WSTRING
+    template
+    BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options<wchar_t>
+    parse_config_file(const char* filename, 
+                      const options_description& desc,
+                      bool allow_unregistered);
+#endif
+
     
 // This versio, which accepts any options without validation, is disabled,
 // in the hope that nobody will need it and we cant drop it altogether.
@@ -248,7 +206,7 @@ namespace boost { namespace program_options {
         return result;
     }
 
-    namespace {
+    namespace detail {
         class prefix_name_mapper {
         public:
             prefix_name_mapper(const std::string& prefix)
@@ -263,7 +221,7 @@ namespace boost { namespace program_options {
                     {   
                         // Intel-Win-7.1 does not understand
             // push_back on string.         
-                        result += tolower(s[n]);
+                        result += static_cast<char>(tolower(s[n]));
                     }
                 }
                 return result;
@@ -277,7 +235,7 @@ namespace boost { namespace program_options {
     parse_environment(const options_description& desc, 
                       const std::string& prefix)
     {
-        return parse_environment(desc, prefix_name_mapper(prefix));
+        return parse_environment(desc, detail::prefix_name_mapper(prefix));
     }
 
     BOOST_PROGRAM_OPTIONS_DECL parsed_options

src/positional_options.cpp

@@ -17,7 +17,7 @@ namespace boost { namespace program_options {
     positional_options_description::positional_options_description()
     {}
 
-    void
+    positional_options_description&
     positional_options_description::add(const char* name, int max_count)
     {
         assert(max_count != -1 || m_trailing.empty());
@@ -27,14 +27,14 @@ namespace boost { namespace program_options {
         else {
             m_names.resize(m_names.size() + max_count, name);
         }
-        
+        return *this;
     }
 
     unsigned
     positional_options_description::max_total_count() const
     {
         return m_trailing.empty() ? 
-        m_names.size() : std::numeric_limits<unsigned>::max();
+          static_cast<unsigned>(m_names.size()) : (std::numeric_limits<unsigned>::max)();
     }
     
     const std::string& 

src/split.cpp

@@ -0,0 +1,62 @@
+// Copyright Sascha Ochsenknecht 2009.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#define BOOST_PROGRAM_OPTIONS_SOURCE
+
+#include <boost/program_options/parsers.hpp>
+#include <boost/tokenizer.hpp>
+
+#include <string>
+#include <vector>
+
+namespace boost { namespace program_options { namespace detail {
+
+   template< class charT >
+   std::vector<std::basic_string<charT> > 
+   split_unix(
+         const std::basic_string<charT>& cmdline, 
+         const std::basic_string<charT>& seperator, 
+         const std::basic_string<charT>& quote, 
+         const std::basic_string<charT>& escape)
+   {   
+      typedef boost::tokenizer< boost::escaped_list_separator<charT>, 
+            typename std::basic_string<charT>::const_iterator, 
+            std::basic_string<charT> >  tokenizerT;
+         
+      tokenizerT tok(cmdline.begin(), cmdline.end(), 
+                boost::escaped_list_separator< charT >(escape, seperator, quote));
+         
+      std::vector< std::basic_string<charT> > result;
+      for (typename tokenizerT::iterator cur_token(tok.begin()), end_token(tok.end()); cur_token != end_token; ++cur_token) {
+         if (!cur_token->empty())
+            result.push_back(*cur_token);
+      }
+      return result;
+   }
+   
+}}}   // namespace
+
+namespace boost { namespace program_options {
+
+   // Take a command line string and splits in into tokens, according
+   // to the given collection of seperators chars.
+   BOOST_PROGRAM_OPTIONS_DECL std::vector<std::string> 
+   split_unix(const std::string& cmdline, const std::string& seperator, 
+         const std::string& quote, const std::string& escape)
+   {
+      return detail::split_unix< char >(cmdline, seperator, quote, escape);
+   }
+
+#ifndef BOOST_NO_STD_WSTRING
+   BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
+   split_unix(const std::wstring& cmdline, const std::wstring& seperator, 
+         const std::wstring& quote, const std::wstring& escape)
+   {
+      return detail::split_unix< wchar_t >(cmdline, seperator, quote, escape);
+   }
+#endif
+
+}}  // namespace
+

src/utf8_codecvt_facet.cpp

@@ -1,360 +1,21 @@
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// utf8_codecvt_facet.cpp
+// Copyright Vladimir Prus 2004.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-// Copyright © 2001 Ronald Garcia, Indiana University (garcia@osl.iu.edu)
-// Andrew Lumsdaine, Indiana University (lums@osl.iu.edu). 
-// Use, modification and distribution is subject to the Boost Software
-// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
-// http://www.boost.org/LICENSE_1_0.txt)
-
-#include <cstdlib> // for multi-byte converson routines
-
-#include <cassert>
 #define BOOST_PROGRAM_OPTIONS_SOURCE
-#include <boost/program_options/detail/utf8_codecvt_facet.hpp>
+#include <boost/program_options/config.hpp>
 
-#include <boost/limits.hpp>
-#include <boost/config.hpp>
+#define BOOST_UTF8_BEGIN_NAMESPACE \
+     namespace boost { namespace program_options { namespace detail {
 
-// If we don't have wstring, then Unicode support 
-// is not available anyway, so we don't need to even
-// compiler this file. This also fixes the problem
-// with mingw, which can compile this file, but will
-// generate link error when building DLL.
-#ifndef BOOST_NO_STD_WSTRING
+#define BOOST_UTF8_END_NAMESPACE }}}
+#define BOOST_UTF8_DECL BOOST_PROGRAM_OPTIONS_DECL
 
-namespace boost { namespace program_options { namespace detail {
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// implementation for wchar_t
+#include <boost/detail/utf8_codecvt_facet.ipp>
 
-// Translate incoming UTF-8 into UCS-4
-std::codecvt_base::result utf8_codecvt_facet_wchar_t::do_in(
-    mbstate_t& state, 
-    const char * from,
-    const char * from_end, 
-    const char * & from_next,
-    wchar_t * to, 
-    wchar_t * to_end, 
-    wchar_t * & to_next
-) const {
-    // Basic algorithm:  The first octet determines how many
-    // octets total make up the UCS-4 character.  The remaining
-    // "continuing octets" all begin with "10". To convert, subtract
-    // the amount that specifies the number of octets from the first
-    // octet.  Subtract 0x80 (1000 0000) from each continuing octet,
-    // then mash the whole lot together.  Note that each continuing
-    // octet only uses 6 bits as unique values, so only shift by
-    // multiples of 6 to combine.
-    while (from != from_end && to != to_end) {
 
-        // Error checking   on the first octet
-        if (invalid_leading_octet(*from)){
-            from_next = from;
-            to_next = to;
-            return std::codecvt_base::error;
-        }
+#undef BOOST_UTF8_BEGIN_NAMESPACE
+#undef BOOST_UTF8_END_NAMESPACE
+#undef BOOST_UTF8_DECL
 
-        // The first octet is   adjusted by a value dependent upon 
-        // the number   of "continuing octets" encoding the character
-        const   int cont_octet_count = get_cont_octet_count(*from);
-        const   wchar_t octet1_modifier_table[] =   {
-            0x00, 0xc0, 0xe0, 0xf0, 0xf8, 0xfc
-        };
-
-        // The unsigned char conversion is necessary in case char is
-        // signed   (I learned this the hard way)
-        wchar_t ucs_result = 
-            (unsigned char)(*from++) - octet1_modifier_table[cont_octet_count];
-
-        // Invariants   : 
-        //   1) At the start of the loop,   'i' continuing characters have been
-        //    processed 
-        //   2) *from   points to the next continuing character to be processed.
-        int i   = 0;
-        while(i != cont_octet_count && from != from_end) {
-
-            // Error checking on continuing characters
-            if (invalid_continuing_octet(*from)) {
-                from_next   = from;
-                to_next =   to;
-                return std::codecvt_base::error;
-            }
-
-            ucs_result *= (1 << 6); 
-
-            // each continuing character has an extra (10xxxxxx)b attached to 
-            // it that must be removed.
-            ucs_result += (unsigned char)(*from++) - 0x80;
-            ++i;
-        }
-
-        // If   the buffer ends with an incomplete unicode character...
-        if (from == from_end && i   != cont_octet_count) {
-            // rewind "from" to before the current character translation
-            from_next = from - (i+1); 
-            to_next = to;
-            return std::codecvt_base::partial;
-        }
-        *to++   = ucs_result;
-    }
-    from_next = from;
-    to_next = to;
-
-    // Were we done converting or did we run out of destination space?
-    if(from == from_end) return std::codecvt_base::ok;
-    else return std::codecvt_base::partial;
-}
-
-std::codecvt_base::result utf8_codecvt_facet_wchar_t::do_out(
-    mbstate_t& state, 
-    const wchar_t *   from,
-    const wchar_t * from_end, 
-    const wchar_t * & from_next,
-    char * to, 
-    char * to_end, 
-    char * & to_next
-) const
-{
-    // RG - consider merging this table with the other one
-    const wchar_t octet1_modifier_table[] = {
-        0x00, 0xc0, 0xe0, 0xf0, 0xf8, 0xfc
-    };
-
-    wchar_t max_wchar = std::numeric_limits<wchar_t>::max();
-    while (from != from_end && to != to_end) {
-
-        // Check for invalid UCS-4 character
-        if (*from  > max_wchar) {
-            from_next = from;
-            to_next = to;
-            return std::codecvt_base::error;
-        }
-
-        int cont_octet_count = get_cont_octet_out_count(*from);
-
-        // RG  - comment this formula better
-        int shift_exponent = (cont_octet_count) *   6;
-
-        // Process the first character
-        *to++ = octet1_modifier_table[cont_octet_count] +
-            (unsigned char)(*from / (1 << shift_exponent));
-
-        // Process the continuation characters 
-        // Invariants: At   the start of the loop:
-        //   1) 'i' continuing octets   have been generated
-        //   2) '*to'   points to the next location to place an octet
-        //   3) shift_exponent is   6 more than needed for the next octet
-        int i   = 0;
-        while   (i != cont_octet_count && to != to_end) {
-            shift_exponent -= 6;
-            *to++ = 0x80 + ((*from / (1 << shift_exponent)) % (1 << 6));
-            ++i;
-        }
-        // If   we filled up the out buffer before encoding the character
-        if(to   == to_end && i != cont_octet_count) {
-            from_next = from;
-            to_next = to - (i+1);
-            return std::codecvt_base::partial;
-        }
-        *from++;
-    }
-    from_next = from;
-    to_next = to;
-    // Were we done or did we run out of destination space
-    if(from == from_end) return std::codecvt_base::ok;
-    else return std::codecvt_base::partial;
-}
-
-// How many char objects can I process to get <= max_limit
-// wchar_t objects?
-int utf8_codecvt_facet_wchar_t::do_length(
-    mbstate_t &,
-    const char * from,
-    const char * from_end, 
-    std::size_t max_limit
-) const
-{ 
-    // RG - this code is confusing!  I need a better way to express it.
-    // and test cases.
-
-    // Invariants:
-    // 1) last_octet_count has the size of the last measured character
-    // 2) char_count holds the number of characters shown to fit
-    // within the bounds so far (no greater than max_limit)
-    // 3) from_next points to the octet 'last_octet_count' before the
-    // last measured character.  
-    int last_octet_count=0;
-    std::size_t char_count = 0;
-    const char* from_next = from;
-    // Use "<" because the buffer may represent incomplete characters
-    while (from_next+last_octet_count <= from_end && char_count <= max_limit) {
-        from_next += last_octet_count;
-        last_octet_count = (get_octet_count(*from_next));
-        ++char_count;
-    }
-    return from_next-from_end;
-}
-
-unsigned int utf8_codecvt_facet_wchar_t::get_octet_count(
-    unsigned char   lead_octet
-){
-    // if the 0-bit (MSB) is 0, then 1 character
-    if (lead_octet <= 0x7f) return 1;
-
-    // Otherwise the count number of consecutive 1 bits starting at MSB
-//    assert(0xc0 <= lead_octet && lead_octet <= 0xfd);
-
-    if (0xc0 <= lead_octet && lead_octet <= 0xdf) return 2;
-    else if (0xe0 <= lead_octet && lead_octet <= 0xef) return 3;
-    else if (0xf0 <= lead_octet && lead_octet <= 0xf7) return 4;
-    else if (0xf8 <= lead_octet && lead_octet <= 0xfb) return 5;
-    else return 6;
-}
-}}}
-
-namespace {
-template<std::size_t s>
-int get_cont_octet_out_count_impl(wchar_t word){
-    if (word < 0x80) {
-        return 0;
-    }
-    if (word < 0x800) {
-        return 1;
-    }
-    return 2;
-}
-
-template<>
-int get_cont_octet_out_count_impl<4>(wchar_t word){
-    if (word < 0x80) {
-        return 0;
-    }
-    if (word < 0x800) {
-        return 1;
-    }
-    if (word < 0x10000) {
-        return 2;
-    }
-    if (word < 0x200000) {
-        return 3;
-    }
-    if (word < 0x4000000) {
-        return 4;
-    }
-    return 5;
-}
-
-} // namespace anonymous
-
-namespace boost { namespace program_options { namespace detail {
-// How many "continuing octets" will be needed for this word
-// ==   total octets - 1.
-int utf8_codecvt_facet_wchar_t::get_cont_octet_out_count(
-    wchar_t word
-) const {
-    return get_cont_octet_out_count_impl<sizeof(wchar_t)>(word);
-}
-}}}
-
-#if 0 // not used?
-/////////1/////////2/////////3/////////4/////////5/////////6/////////7/////////8
-// implementation for char
-
-std::codecvt_base::result utf8_codecvt_facet_char::do_in(
-    mbstate_t & state, 
-    const char * from, 
-    const char * from_end, 
-    const char * & from_next,
-    char * to, 
-    char * to_end, 
-    char * & to_next
-) const
-{
-    while(from_next < from_end){
-        wchar_t w;
-        wchar_t *wnext = & w;
-        utf8_codecvt_facet_wchar_t::result ucs4_result;
-        ucs4_result = base_class::do_in(
-            state,
-            from, from_end, from_next,
-            wnext, wnext + 1, wnext
-        );
-        if(codecvt_base::ok != ucs4_result)
-            return ucs4_result;
-        // if the conversion succeeds. 
-        int length = std::wctomb(to_next, w);
-//        assert(-1 != length);
-        to_next += length;
-    }
-    return codecvt_base::ok;
-}
-
-std::codecvt_base::result utf8_codecvt_facet_char::do_out(
-    std::mbstate_t & state, 
-    const char * from,
-    const char * from_end, 
-    const char * & from_next,
-    char * to, 
-    char * to_end, 
-    char * & to_next
-) const
-{
-    while(from_next < from_end){
-        wchar_t w;
-        int result = std::mbtowc(&w, from_next,  MB_LENGTH_MAX);
- //       assert(-1 != result);
-        from_next += result;
-        utf8_codecvt_facet_wchar_t::result ucs4_result;
-
-        const wchar_t *wptr = & w;
-        ucs4_result = base_class::do_out(
-            state,
-            wptr, wptr+1, wptr,
-            to_next, to_end, to_next
-        );
-        if(codecvt_base::ok != ucs4_result)
-            return ucs4_result;     
-    }
-    return codecvt_base::ok;
-}
-
-// How many bytes objects can I process to get <= max_limit
-// char objects?
-int utf8_codecvt_facet_char::do_length(
-    const mbstate_t & initial_state,
-    const char * from_next,
-    const char * from_end, 
-    std::size_t max_limit
-) const
-{
-    int total_length = 0;
-    const char *from = from_next;
-    mbstate_t state = initial_state;
-    while(from_next < from_end){
-        wchar_t w;
-        wchar_t *wnext = & w;
-        utf8_codecvt_facet_wchar_t::result ucs4_result;
-        ucs4_result = base_class::do_in(
-            state,
-            from_next, from_end, from_next,
-            wnext, wnext + 1, wnext
-        );
-
-        if(codecvt_base::ok != ucs4_result)
-            break;
-
-        char carray[MB_LENGTH_MAX];
-        std::size_t count = wctomb(carray, w);
-        if(count > max_limit)
-            break;
-
-        max_limit -= count;
-        total_length = from_next - from;
-    }
-    return total_length;
-}
-}
-
-#endif
-
-#endif

src/value_semantic.cpp

@@ -7,11 +7,31 @@
 #include <boost/program_options/config.hpp>
 #include <boost/program_options/value_semantic.hpp>
 #include <boost/program_options/detail/convert.hpp>
+#include <boost/program_options/detail/cmdline.hpp>
+#include <set>
+
+#include <cctype>
 
 namespace boost { namespace program_options {
 
     using namespace std;
 
+
+#ifndef BOOST_NO_STD_WSTRING
+    namespace
+    {
+        std::string convert_value(const std::wstring& s)
+        {
+            try {
+                return to_local_8_bit(s);
+            }
+            catch(const std::exception&) {
+                return "<unrepresentable unicode string>";
+            }
+        }
+    }
+#endif
+
     void 
     value_semantic_codecvt_helper<char>::
     parse(boost::any& value_store, 
@@ -28,7 +48,8 @@ namespace boost { namespace program_options {
             }
             xparse(value_store, local_tokens);
 #else
-            throw std::runtime_error("UTF-8 conversion not supported.");
+            boost::throw_exception(
+                std::runtime_error("UTF-8 conversion not supported."));
 #endif
         } else {
             // Already in local encoding, pass unmodified
@@ -68,15 +89,35 @@ namespace boost { namespace program_options {
     {
         return arg;
     }
+    
+    unsigned 
+    untyped_value::min_tokens() const
+    {
+        if (m_zero_tokens)
+            return 0;
+        else
+            return 1;
+    }
+
+    unsigned 
+    untyped_value::max_tokens() const
+    {
+        if (m_zero_tokens)
+            return 0;
+        else
+            return 1;
+    }
+
 
     void 
     untyped_value::xparse(boost::any& value_store,
                           const std::vector<std::string>& new_tokens) const
     {
         if (!value_store.empty()) 
-            throw multiple_occurrences("multiple_occurrences");
+            boost::throw_exception(
+                multiple_occurrences());
         if (new_tokens.size() > 1)
-            throw multiple_values("multiple_values");
+            boost::throw_exception(multiple_values());
         value_store = new_tokens.empty() ? std::string("") : new_tokens.front();
     }
 
@@ -99,8 +140,8 @@ namespace boost { namespace program_options {
     /* Validates bool value.
         Any of "1", "true", "yes", "on" will be converted to "1".<br>
         Any of "0", "false", "no", "off" will be converted to "0".<br>
-        Case is ignored. Regardless of name passed, parameter will always
-        be optional.
+        Case is ignored. The 'xs' vector can either be empty, in which
+        case the value is 'true', or can contain explicit value.
     */
     BOOST_PROGRAM_OPTIONS_DECL void validate(any& v, const vector<string>& xs,
                        bool*, int)
@@ -116,7 +157,7 @@ namespace boost { namespace program_options {
         else if (s == "off" || s == "no" || s == "0" || s == "false")
             v = any(false);
         else
-            throw validation_error("'" + s + "' doesn't look like a bool value.");
+            boost::throw_exception(invalid_bool_value(s));
     }
 
     // This is blatant copy-paste. However, templating this will cause a problem,
@@ -138,19 +179,14 @@ namespace boost { namespace program_options {
         else if (s == L"off" || s == L"no" || s == L"0" || s == L"false")
             v = any(false);
         else
-            throw validation_error("invalid bool value");
+            boost::throw_exception(invalid_bool_value(convert_value(s)));
     }
 #endif
     BOOST_PROGRAM_OPTIONS_DECL 
     void validate(any& v, const vector<string>& xs, std::string*, int)
     {
         check_first_occurrence(v);
-        string s(get_single_string(xs));
-        if (*s.begin() == '\'' && *s.rbegin() == '\'' ||
-            *s.begin() == '"' && *s.rbegin() == '"')
-            v = any(s.substr(1, s.size()-2));
-        else
-            v = any(s);
+        v = any(get_single_string(xs));
     }
 
 #if !defined(BOOST_NO_STD_WSTRING)
@@ -158,12 +194,7 @@ namespace boost { namespace program_options {
     void validate(any& v, const vector<wstring>& xs, std::string*, int)
     {
         check_first_occurrence(v);
-        wstring s(get_single_string(xs));
-        if (*s.begin() == L'\'' && *s.rbegin() == L'\'' ||
-            *s.begin() == L'"' && *s.rbegin() == L'"')
-            v = any(s.substr(1, s.size()-2));
-        else
-            v = any(s);
+        v = any(get_single_string(xs));
     }
 #endif
 
@@ -173,63 +204,225 @@ namespace boost { namespace program_options {
         void check_first_occurrence(const boost::any& value)
         {
             if (!value.empty())
-                throw multiple_occurrences("multiple_occurrences");
+                boost::throw_exception(
+                    multiple_occurrences());
         }
     }
 
 
     invalid_option_value::
     invalid_option_value(const std::string& bad_value)
-    : validation_error(string("invalid option value '")
-                       .append(bad_value).append("'"))
-    {}
+    : validation_error(validation_error::invalid_option_value)
+    {
+        set_substitute("value", bad_value);
+    }
 
 #ifndef BOOST_NO_STD_WSTRING
-
-    namespace
-    {
-        std::string convert_value(const std::wstring& s)
-        {
-            try {
-                return to_local_8_bit(s);
-            }
-            catch(const std::exception&) {
-                return "<unrepresentable unicode string>";
-            }
-        }
-    }
-
     invalid_option_value::
     invalid_option_value(const std::wstring& bad_value)
-    : validation_error(string("invalid option value '")
-                       .append(convert_value(bad_value))
-                       .append("'"))
-    {}
-#endif                       
-
-
-
-    void validation_error::set_option_name(const std::string& option_name)
+    : validation_error(validation_error::invalid_option_value)
     {
-        m_option_name = option_name;
+        set_substitute("value", convert_value(bad_value));
     }
+#endif
 
-    const char* validation_error::what() const throw()
+
+
+    invalid_bool_value::
+    invalid_bool_value(const std::string& bad_value)
+    : validation_error(validation_error::invalid_bool_value)
     {
-        if (!m_option_name.empty())
-        {
-            m_message = "in option '" + m_option_name + "': " 
-                + logic_error::what();
-            return m_message.c_str();
-
-        }
-        else
-        {
-            return logic_error::what();
-        }
+        set_substitute("value", bad_value);
     }
 
 
 
 
+
+
+    error_with_option_name::error_with_option_name( const std::string& template_,
+                                                  const std::string& option_name,
+                                                  const std::string& original_token,
+                                                  int option_style) : 
+                                        error(template_),
+                                        m_option_style(option_style),
+                                        m_error_template(template_)
+    {
+        //                     parameter            |     placeholder               |   value
+        //                     ---------            |     -----------               |   -----
+        set_substitute_default("canonical_option",  "option '%canonical_option%'",  "option");
+        set_substitute_default("value",             "argument ('%value%')",         "argument");
+        set_substitute_default("prefix",            "%prefix%",                     "");
+        m_substitutions["option"] = option_name;
+        m_substitutions["original_token"] = original_token;
+    }
+
+
+    const char* error_with_option_name::what() const throw()
+    {
+        // will substitute tokens each time what is run()
+        substitute_placeholders(m_error_template);
+
+        return m_message.c_str();
+    }
+
+    void error_with_option_name::replace_token(const string& from, const string& to) const
+    {
+        for (;;)
+        {
+            std::size_t pos = m_message.find(from.c_str(), 0, from.length());
+            // not found: all replaced
+            if (pos == std::string::npos)
+                return;
+            m_message.replace(pos, from.length(), to);
+        }
+    }
+
+    string error_with_option_name::get_canonical_option_prefix() const
+    {
+        switch (m_option_style)
+        {
+        case command_line_style::allow_dash_for_short:
+            return "-";
+        case command_line_style::allow_slash_for_short:
+            return "/";
+        case command_line_style::allow_long_disguise:
+            return "-";
+        case command_line_style::allow_long:
+            return "--";
+        case 0:
+            return "";
+        }
+        throw std::logic_error("error_with_option_name::m_option_style can only be "
+                               "one of [0, allow_dash_for_short, allow_slash_for_short, "
+                               "allow_long_disguise or allow_long]");
+    }
+
+
+    string error_with_option_name::get_canonical_option_name() const
+    {
+        if (!m_substitutions.find("option")->second.length())
+            return m_substitutions.find("original_token")->second;
+
+        string original_token   = strip_prefixes(m_substitutions.find("original_token")->second);
+        string option_name      = strip_prefixes(m_substitutions.find("option")->second);
+
+        //  For long options, use option name
+        if (m_option_style == command_line_style::allow_long        || 
+             m_option_style == command_line_style::allow_long_disguise)
+            return get_canonical_option_prefix() + option_name;
+
+        //  For short options use first letter of original_token
+        if (m_option_style && original_token.length())
+            return get_canonical_option_prefix() + original_token[0];
+
+        // no prefix
+        return option_name;
+    }
+
+
+    void error_with_option_name::substitute_placeholders(const string& error_template) const
+    {
+        m_message = error_template;
+        std::map<std::string, std::string> substitutions(m_substitutions);
+        substitutions["canonical_option"]   = get_canonical_option_name();
+        substitutions["prefix"]             = get_canonical_option_prefix();
+
+
+        //
+        //  replace placeholder with defaults if values are missing 
+        // 
+        for (map<string, string_pair>::const_iterator iter = m_substitution_defaults.begin();
+              iter != m_substitution_defaults.end(); ++iter)
+        {
+            // missing parameter: use default
+            if (substitutions.count(iter->first) == 0 ||
+                substitutions[iter->first].length() == 0)
+                replace_token(iter->second.first, iter->second.second);
+        }
+
+
+        //
+        //  replace placeholder with values
+        //  placeholder are denoted by surrounding '%'
+        // 
+        for (map<string, string>::iterator iter = substitutions.begin();
+              iter != substitutions.end(); ++iter)
+            replace_token('%' + iter->first + '%', iter->second);
+    }
+
+
+    void ambiguous_option::substitute_placeholders(const string& original_error_template) const
+    {
+        // For short forms, all alternatives must be identical, by
+        //      definition, to the specified option, so we don't need to
+        //      display alternatives
+        if (m_option_style == command_line_style::allow_dash_for_short || 
+            m_option_style == command_line_style::allow_slash_for_short)
+        {
+            error_with_option_name::substitute_placeholders(original_error_template);
+            return;
+        }
+
+
+        string error_template  = original_error_template;
+        // remove duplicates using std::set
+        std::set<std::string>   alternatives_set (m_alternatives.begin(), m_alternatives.end());
+        std::vector<std::string> alternatives_vec (alternatives_set.begin(), alternatives_set.end());
+
+        error_template += " and matches ";
+        // Being very cautious: should be > 1 alternative!
+        if (alternatives_vec.size() > 1)
+        {
+            for (unsigned i = 0; i < alternatives_vec.size() - 1; ++i)
+                error_template += "'%prefix%" + alternatives_vec[i] + "', ";
+            error_template += "and ";
+        }
+
+        // there is a programming error if multiple options have the same name...
+        if (m_alternatives.size() > 1 && alternatives_vec.size() == 1)
+            error_template += "different versions of ";
+
+        error_template += "'%prefix%" + alternatives_vec.back() + "'";
+
+
+        // use inherited logic
+        error_with_option_name::substitute_placeholders(error_template);
+    }
+
+
+
+
+
+
+    string 
+    validation_error::get_template(kind_t kind)
+    {
+        // Initially, store the message in 'const char*' variable,
+        // to avoid conversion to std::string in all cases.
+        const char* msg;
+        switch(kind)
+        {
+        case invalid_bool_value:
+            msg = "the argument ('%value%') for option '%canonical_option%' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'";
+            break;
+        case invalid_option_value:
+            msg = "the argument ('%value%') for option '%canonical_option%' is invalid";
+            break;
+        case multiple_values_not_allowed:
+            msg = "option '%canonical_option%' only takes a single argument";
+            break;
+        case at_least_one_value_required:
+            msg = "option '%canonical_option%' requires at least one argument";
+            break;
+        // currently unused
+        case invalid_option:
+            msg = "option '%canonical_option%' is not valid";
+            break;
+        default:
+            msg = "unknown error";
+        }
+        return msg;
+    }
+
 }}

src/variables_map.cpp

@@ -17,12 +17,15 @@ namespace boost { namespace program_options {
 
     using namespace std;
 
-    // First, performs semantic actions for 'oa'. 
-    // Then, stores in 'm' all options that are defined in 'desc'. 
-    BOOST_PROGRAM_OPTIONS_DECL 
+    // First, performs semantic actions for 'oa'.
+    // Then, stores in 'm' all options that are defined in 'desc'.
+    BOOST_PROGRAM_OPTIONS_DECL
     void store(const parsed_options& options, variables_map& xm,
                bool utf8)
-    {       
+    {
+        // TODO: what if we have different definition
+        // for the same option name during different calls
+        // 'store'.
         assert(options.description);
         const options_description& desc = *options.description;
 
@@ -30,88 +33,124 @@ namespace boost { namespace program_options {
         // variables_map. Ehmm.. messy.
         std::map<std::string, variable_value>& m = xm;
 
-        // The set of existing values that should not be changed.
-        std::set<std::string> final;
-        for (map<string, variable_value>::iterator k = m.begin(); 
-             k != m.end(); 
-             ++k) 
+        std::set<std::string> new_final;
+
+        // Declared once, to please Intel in VC++ mode;
+        unsigned i;
+
+        // Declared here so can be used to provide context for exceptions
+        string option_name;
+        string original_token;
+
+#ifndef BOOST_NO_EXCEPTIONS
+        try
+#endif
         {
-            if (!k->second.defaulted()) {
-                // TODO: what if we have different definition
-                // for the same option name during different calls
-                // 'store'.
-                bool composing = desc.count(k->first)
-                    && desc.find(k->first).semantic()->is_composing();
 
-                if (!composing)
-                    final.insert(k->first);
-            }
-        }
+            // First, convert/store all given options
+            for (i = 0; i < options.options.size(); ++i) {
 
-        // First, convert/store all given options
-        for (size_t i = 0; i < options.options.size(); ++i) {
+                option_name = options.options[i].string_key;
+                // Skip positional options without name
+                if (option_name.empty())
+                    continue;
 
-            const string& name = options.options[i].string_key;
-            // Skip positional options without name
-            if (name.empty())
-                continue;
+                // Ignore unregistered option. The 'unregistered'
+                // field can be true only if user has explicitly asked
+                // to allow unregistered options. We can't store them
+                // to variables map (lacking any information about paring),
+                // so just ignore them.
+                if (options.options[i].unregistered)
+                    continue;
 
-            // If option has final value, skip this assignment
-            if (final.count(name))
-                continue;
+                // If option has final value, skip this assignment
+                if (xm.m_final.count(option_name))
+                    continue;
 
-            // Ignore options which are not described
-            if (desc.count(name) == 0)
-                continue;
+                original_token = options.options[i].original_tokens.size() ?
+                                        options.options[i].original_tokens[0]     : "";
+                const option_description& d = desc.find(option_name, false,
+                                                        false, false);
 
-            const option_description& d = desc.find(name);
+                variable_value& v = m[option_name];
+                if (v.defaulted()) {
+                    // Explicit assignment here erases defaulted value
+                    v = variable_value();
+                }
 
-            variable_value& v = m[name];            
-            if (v.defaulted()) {
-                // Explicit assignment here erases defaulted value
-                v = variable_value();
-            }
-            try {
                 d.semantic()->parse(v.value(), options.options[i].value, utf8);
+
+                v.m_value_semantic = d.semantic();
+
+                // The option is not composing, and the value is explicitly
+                // provided. Ignore values of this option for subsequent
+                // calls to 'store'. We store this to a temporary set,
+                // so that several assignment inside *this* 'store' call
+                // are allowed.
+                if (!d.semantic()->is_composing())
+                    new_final.insert(option_name);
             }
-            catch(validation_error& e)
-            {
-                e.set_option_name(name);
-                throw;
-            }
-            v.m_value_semantic = d.semantic();
         }
-        
-        // Second, apply default values.
-        set<string> keys = desc.primary_keys();
-        for (set<string>::const_iterator j = keys.begin(); j != keys.end(); ++j)
-            if (m.count(*j) == 0) {
-                const option_description& d = desc.find(*j);
+#ifndef BOOST_NO_EXCEPTIONS
+        catch(error_with_option_name& e)
+        {
+            // add context and rethrow
+            e.add_context(option_name, original_token, options.m_options_prefix);
+            throw;
+        }
+#endif
+        xm.m_final.insert(new_final.begin(), new_final.end());
+
+
+
+        // Second, apply default values and store required options.
+        const vector<shared_ptr<option_description> >& all = desc.options();
+        for(i = 0; i < all.size(); ++i)
+        {
+            const option_description& d = *all[i];
+            string key = d.key("");
+            // FIXME: this logic relies on knowledge of option_description
+            // internals.
+            // The 'key' is empty if options description contains '*'.
+            // In that
+            // case, default value makes no sense at all.
+            if (key.empty())
+            {
+                continue;
+            }
+            if (m.count(key) == 0) {
 
                 boost::any def;
                 if (d.semantic()->apply_default(def)) {
-                    m[*j] = variable_value(def, true);
-                    m[*j].m_value_semantic = d.semantic();
+                    m[key] = variable_value(def, true);
+                    m[key].m_value_semantic = d.semantic();
                 }
-            }        
+            }
+
+            // add empty value if this is an required option
+            if (d.semantic()->is_required()) {
+
+                // For option names specified in multiple ways, e.g. on the command line,
+                // config file etc, the following precedence rules apply:
+                //  "--"  >  ("-" or "/")  >  ""
+                //  Precedence is set conveniently by a single call to length()
+                string canonical_name = d.canonical_display_name(options.m_options_prefix);
+                if (canonical_name.length() > xm.m_required[key].length())
+                    xm.m_required[key] = canonical_name;
+            }
+        }
     }
 
-    BOOST_PROGRAM_OPTIONS_DECL 
+    BOOST_PROGRAM_OPTIONS_DECL
     void store(const wparsed_options& options, variables_map& m)
     {
         store(options.utf8_encoded_options, m, true);
     }
 
-    BOOST_PROGRAM_OPTIONS_DECL 
+    BOOST_PROGRAM_OPTIONS_DECL
     void notify(variables_map& vm)
-    {        
-        // Lastly, run notify actions.
-        for (map<string, variable_value>::iterator k = vm.begin(); 
-             k != vm.end(); 
-             ++k) 
-        {
-            k->second.m_value_semantic->notify(k->second.value());
-        }               
+    {
+        vm.notify();
     }
 
     abstract_variables_map::abstract_variables_map()
@@ -123,7 +162,7 @@ namespace boost { namespace program_options {
     : m_next(next)
     {}
 
-    const variable_value& 
+    const variable_value&
     abstract_variables_map::operator[](const std::string& name) const
     {
         const variable_value& v = get(name);
@@ -139,7 +178,7 @@ namespace boost { namespace program_options {
         }
     }
 
-    void 
+    void
     abstract_variables_map::next(abstract_variables_map* next)
     {
         m_next = next;
@@ -152,6 +191,13 @@ namespace boost { namespace program_options {
     : abstract_variables_map(next)
     {}
 
+    void variables_map::clear()
+    {
+        std::map<std::string, variable_value>::clear();
+        m_final.clear();
+        m_required.clear();
+    }
+
     const variable_value&
     variables_map::get(const std::string& name) const
     {
@@ -162,4 +208,41 @@ namespace boost { namespace program_options {
         else
             return i->second;
     }
+
+    void
+    variables_map::notify()
+    {
+        // This checks if all required options occur
+        for (map<string, string>::const_iterator r = m_required.begin();
+             r != m_required.end();
+             ++r)
+        {
+            const string& opt = r->first;
+            const string& display_opt = r->second;
+            map<string, variable_value>::const_iterator iter = find(opt);
+            if (iter == end() || iter->second.empty())
+            {
+                boost::throw_exception(required_option(display_opt));
+
+            }
+        }
+
+        // Lastly, run notify actions.
+        for (map<string, variable_value>::iterator k = begin();
+             k != end();
+             ++k)
+        {
+            /* Users might wish to use variables_map to store their own values
+               that are not parsed, and therefore will not have value_semantics
+               defined. Do not crash on such values. In multi-module programs,
+               one module might add custom values, and the 'notify' function
+               will be called after that, so we check that value_sematics is
+               not NULL. See:
+                   https://svn.boost.org/trac/boost/ticket/2782
+            */
+            if (k->second.m_value_semantic)
+                k->second.m_value_semantic->notify(k->second.value());
+        }
+    }
+
 }}

src/winmain.cpp

@@ -7,29 +7,32 @@
 #include <boost/program_options/parsers.hpp>
 #include <cctype>
 
+using std::size_t;
+
 #ifdef _WIN32
 namespace boost { namespace program_options {
 
-    using namespace std;
-
-    // The rules for windows command line are pretty funny, see
+    // Take a command line string and splits in into tokens, according
+    // to the rules windows command line processor uses.
+    // 
+    // The rules are pretty funny, see
     //    http://article.gmane.org/gmane.comp.lib.boost.user/3005
     //    http://msdn.microsoft.com/library/en-us/vccelng/htm/progs_12.asp
-    
     BOOST_PROGRAM_OPTIONS_DECL
     std::vector<std::string> split_winmain(const std::string& input)
     {
         std::vector<std::string> result;
 
-        string::const_iterator i = input.begin(), e = input.end();
+        std::string::const_iterator i = input.begin(), e = input.end();
         for(;i != e; ++i)
-            if (!isspace(*i))
+            if (!isspace((unsigned char)*i))
                 break;
        
         if (i != e) {
    
             std::string current;
             bool inside_quoted = false;
+            bool empty_quote = false;
             int backslash_count = 0;
             
             for(; i != e; ++i) {
@@ -38,6 +41,7 @@ namespace boost { namespace program_options {
                     // n/2 backslashes and is a quoted block delimiter
                     if (backslash_count % 2 == 0) {
                         current.append(backslash_count / 2, '\\');
+                        empty_quote = inside_quoted && current.empty();
                         inside_quoted = !inside_quoted;
                         // '"' preceded by odd number (n) of backslashes generates
                         // (n-1)/2 backslashes and is literal quote.
@@ -55,11 +59,12 @@ namespace boost { namespace program_options {
                         current.append(backslash_count, '\\');
                         backslash_count = 0;
                     }
-                    if (isspace(*i) && !inside_quoted) {
+                    if (isspace((unsigned char)*i) && !inside_quoted) {
                         // Space outside quoted section terminate the current argument
                         result.push_back(current);
                         current.resize(0);
-                        for(;i != e && isspace(*i); ++i)
+                        empty_quote = false; 
+                        for(;i != e && isspace((unsigned char)*i); ++i)
                             ;
                         --i;
                     } else {                  
@@ -74,7 +79,7 @@ namespace boost { namespace program_options {
         
             // If we have non-empty 'current' or we're still in quoted
             // section (even if 'current' is empty), add the last token.
-            if (!current.empty() || inside_quoted)
+            if (!current.empty() || inside_quoted || empty_quote)
                 result.push_back(current);        
         }
         return result;
@@ -84,9 +89,9 @@ namespace boost { namespace program_options {
     BOOST_PROGRAM_OPTIONS_DECL std::vector<std::wstring>
     split_winmain(const std::wstring& cmdline)
     {
-        vector<wstring> result;
-        vector<string> aux = split_winmain(to_internal(cmdline));
-        for (unsigned i = 0, e = result.size(); i < e; ++i)
+        std::vector<std::wstring> result;
+        std::vector<std::string> aux = split_winmain(to_internal(cmdline));
+        for (size_t i = 0, e = aux.size(); i < e; ++i)
             result.push_back(from_utf8(aux[i]));
         return result;        
     }
@@ -94,3 +99,4 @@ namespace boost { namespace program_options {
 
 }}
 #endif
+

test/Jamfile

@@ -1,47 +0,0 @@
-
-subproject libs/program_options/test ;
-
-import testing ;
-
-rule program-options-test ( name )
-{
-    return [ 
-      run $(name).cpp <lib>../build/boost_program_options
-        <lib>../../test/build/boost_test_exec_monitor : :
-        : <include>$(BOOST_ROOT) 
-          std::locale-support ]
-    ;
-}
-
-rule program-options-dll-test ( name )
-{
-    return [ 
-      run $(name).cpp <dll>../build/boost_program_options
-        <lib>../../test/build/boost_test_exec_monitor : :
-        : <include>$(BOOST_ROOT) 
-          <define>BOOST_ALL_DYN_LINK=1
-          <runtime-link>dynamic
-        : $(name)_dll ]
-    ;
-}
-
-
-test-suite program_options : 
-    [ program-options-test options_description_test ]
-    [ program-options-test parsers_test ]
-    [ program-options-test variable_map_test ]
-    [ program-options-test cmdline_test ]
-    [ program-options-test positional_options_test ]
-    [ program-options-test unicode_test ]
-    [ program-options-test winmain ] 
-    [ program-options-dll-test options_description_test ]
-    [ program-options-dll-test parsers_test ]
-    [ program-options-dll-test variable_map_test ]
-    [ program-options-dll-test cmdline_test ]
-    [ program-options-dll-test positional_options_test ]
-    [ program-options-dll-test unicode_test ]
-    [ program-options-dll-test winmain ] 
-    
-    
-    ;
-

test/Jamfile.v2

@@ -1,24 +1,44 @@
+import testing ;
 
 project
     : requirements 
-    <library>../build//program_options
-    <library>/boost/test//boost_test_exec_monitor
-    <hardcode-dll-paths>true
+    <library>../build//boost_program_options
+    <link>static
+    <variant>debug
     
 #    <define>_GLIBCXX_CONCEPT_CHECKS
 #    <define>_GLIBCXX_DEBUG
     ;
+    
+rule po-test ( source : input-file ? )
+{
+    return
+        [ run $(source) : : $(input-file) ]
+        [ run $(source) : : $(input-file) 
+          : <link>shared <define>BOOST_PROGRAM_OPTIONS_DYN_LINK=1
+          : $(source:B)_dll ] 
+    ;   
+}    
 
 test-suite program_options :
 
-    [ run options_description_test.cpp ] 
-    [ run parsers_test.cpp ]
-    [ run variable_map_test.cpp ]
-    [ run cmdline_test.cpp ]
-    [ run positional_options_test.cpp ]
-    [ run unicode_test.cpp ] 
-    [ run winmain.cpp ] 
+    [ po-test options_description_test.cpp ] 
+    [ po-test parsers_test.cpp : config_test.cfg ]
+    [ po-test variable_map_test.cpp ]
+    [ po-test cmdline_test.cpp ]
+    [ po-test positional_options_test.cpp ]
+    [ po-test unicode_test.cpp ] 
+    [ po-test winmain.cpp ] 
+    [ po-test exception_test.cpp ]
+    [ po-test split_test.cpp ]
+    [ po-test unrecognized_test.cpp ]
+    [ po-test required_test.cpp : required_test.cfg ]
+    [ po-test exception_txt_test.cpp ]
+    [ po-test optional_test.cpp ]
+    [ run options_description_test.cpp : : : <rtti>off : options_description_no_rtti_test ]
     ;
         
-exe test_convert : test_convert.cpp ../build//program_options ;   
+exe test_convert : test_convert.cpp ;   
 
+# `quick` target (for CI)
+run quick.cpp : --path=initial ;

test/cmdline_test.cpp

@@ -3,21 +3,20 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-
 #include <boost/program_options/cmdline.hpp>
+#include <boost/program_options/options_description.hpp>
 #include <boost/program_options/detail/cmdline.hpp>
 using namespace boost::program_options;
 using boost::program_options::detail::cmdline;
 
-
-#include <boost/test/test_tools.hpp>
-
 #include <iostream>
 #include <sstream>
 #include <vector>
 #include <cassert>
 using namespace std;
 
+#include "minitest.hpp"
+
 /* To facilitate testing, declare a number of error codes. Otherwise,
    we'd have to specify the type of exception that should be thrown.
 */
@@ -31,6 +30,7 @@ const int s_short_adjacent_not_allowed = 5;
 const int s_empty_adjacent_parameter = 6;
 const int s_missing_parameter = 7;
 const int s_extra_parameter = 8;
+const int s_unrecognized_line = 9;
 
 int translate_syntax_error_kind(invalid_command_line_syntax::kind_t k)
 {
@@ -41,6 +41,7 @@ int translate_syntax_error_kind(invalid_command_line_syntax::kind_t k)
         invalid_command_line_syntax::empty_adjacent_parameter,
         invalid_command_line_syntax::missing_parameter,
         invalid_command_line_syntax::extra_parameter,
+        invalid_command_line_syntax::unrecognized_line 
     };
     invalid_command_line_syntax::kind_t *b, *e, *i;
     b = table;
@@ -50,19 +51,19 @@ int translate_syntax_error_kind(invalid_command_line_syntax::kind_t k)
     return std::distance(b, i) + 3;
 }
 
-
 struct test_case {
     const char* input;
     int expected_status;
     const char* expected_result;
 };
 
+
 /* Parses the syntax description in 'syntax' and initialized
    'cmd' accordingly' 
    The "boost::program_options" in parameter type is needed because CW9 
    has std::detail and it causes an ambiguity.
 */
-void apply_syntax(cmdline& cmd, 
+void apply_syntax(options_description& desc, 
                   const char* syntax)
 {
    
@@ -70,32 +71,28 @@ void apply_syntax(cmdline& cmd,
     stringstream ss;
     ss << syntax;
     while(ss >> s) {
-        string long_name;
-        char short_name = '\0';
-        char properties = '|';
+        value_semantic* v = 0;
         
         if (*(s.end()-1) == '=') {
-            properties = ':';
+            v = value<string>();
             s.resize(s.size()-1);
         } else if (*(s.end()-1) == '?') {
-            properties = '?';
+            v = value<string>()->implicit_value("default");
             s.resize(s.size()-1);
         } else if (*(s.end()-1) == '*') {
-            properties = '*';
+            v = value<vector<string> >()->multitoken();
             s.resize(s.size()-1);
         } else if (*(s.end()-1) == '+') {
-            properties = '+';
+            v = value<vector<string> >()->multitoken();
             s.resize(s.size()-1);
         }
-        string::size_type n = s.find(',');
-        if (n == string::npos) {
-            long_name = s;
+        if (v) {
+            desc.add_options()
+                (s.c_str(), v, "");
         } else {
-            assert(n == s.size()-2);
-            long_name = s.substr(0, s.size()-2);
-            short_name = *s.rbegin();
+            desc.add_options()
+                (s.c_str(), "");
         }
-        cmd.add_option(long_name, short_name, properties, 1);
     }
 }
 
@@ -114,38 +111,44 @@ void test_cmdline(const char* syntax,
                 xinput.push_back(s);
             }
         }
-        cmdline cmd(xinput, style);
+        options_description desc;
+        apply_syntax(desc, syntax);
+
+        cmdline cmd(xinput);
+        cmd.style(style);
+        cmd.set_options_description(desc);
 
-        apply_syntax(cmd, syntax);
 
         string result;
         int status = 0;
 
         try {
-            while(++cmd) {
-                if (cmd.at_argument()) {
+            vector<option> options = cmd.run();
+
+            for(unsigned j = 0; j < options.size(); ++j)
+            {
+                option opt = options[j];
+
+                if (opt.position_key != -1) {
                     if (!result.empty())
                         result += " ";
-                    result += cmd.argument();
+                    result += opt.value[0];
                 } else {
                     if (!result.empty())
                         result += " ";
-                    if (*cmd.option_name().rbegin() != '*')
-                        result += cmd.option_name() + ":";
-                    else
-                        result += cmd.raw_option_name() + ":";
-                    for (size_t i = 0; i < cmd.option_values().size(); ++i) {
-                        if (i != 0)
+                    result += opt.string_key + ":";
+                    for (size_t k = 0; k < opt.value.size(); ++k) {
+                        if (k != 0)
                             result += "-";
-                        result += cmd.option_values()[i];
+                        result += opt.value[k];
                     }                    
                 }
             }
         }
-        catch(unknown_option& e) {
+        catch(unknown_option&) {
             status = s_unknown_option;
         }
-        catch(ambiguous_option& e) {
+        catch(ambiguous_option&) {
             status = s_ambiguous_option;
         }
         catch(invalid_command_line_syntax& e) {
@@ -177,34 +180,28 @@ void test_long_options()
         {"--foo=13", s_extra_parameter, ""},
 
         // Test option with required parameter
-
         {"--bar=", s_empty_adjacent_parameter, ""},
         {"--bar", s_missing_parameter, ""},
-        {"--bar=123", s_success, "bar:123"},
 
-        // Test option with optional parameter
-        {"--baz", s_success, "baz:"},
-        {"--baz=7", s_success, "baz:7"},
-        {0}
+        {"--bar=123", s_success, "bar:123"},
+        {0, 0, 0}
     };
-    test_cmdline("foo bar= baz?", style, test_cases1);
+    test_cmdline("foo bar=", style, test_cases1);
+
 
     style = cmdline::style_t(
         allow_long | long_allow_next);
 
     test_case test_cases2[] = {
-        {"--foo", s_success, "foo:"},
-        {"--bar=10", s_long_adjacent_not_allowed, ""},
         {"--bar 10", s_success, "bar:10"},
         {"--bar", s_missing_parameter,  ""},
-        {"--bar --foo", s_missing_parameter, ""},
-        {"--baz", s_success, "baz:"},
-        {"--baz 10", s_success, "baz:10"},
-        {"--baz --foo", s_success, "baz: foo:"},
-        {0}
+        // Since --bar accepts a parameter, --foo is
+        // considered a value, even though it looks like
+        // an option.
+        {"--bar --foo", s_success, "bar:--foo"},
+        {0, 0, 0}
     };
-    test_cmdline("foo bar= baz?", style, test_cases2);
-
+    test_cmdline("foo bar=", style, test_cases2);
     style = cmdline::style_t(
         allow_long | long_allow_adjacent
         | long_allow_next);
@@ -212,12 +209,9 @@ void test_long_options()
     test_case test_cases3[] = {
         {"--bar=10", s_success, "bar:10"},
         {"--bar 11", s_success, "bar:11"},
-        {"--baz=12", s_success, "baz:12"},
-        {"--baz 13", s_success, "baz:13"},
-        {"--baz --foo", s_success, "baz: foo:"},
-        {0}
+        {0, 0, 0}
     };
-    test_cmdline("foo bar= baz?", style, test_cases3);
+    test_cmdline("foo bar=", style, test_cases3);
 
     style = cmdline::style_t(
         allow_long | long_allow_adjacent
@@ -231,7 +225,7 @@ void test_long_options()
         {"--bar=Ab", s_success, "bar:Ab"},
         {"--Bar=ab", s_success, "bar:ab"},
         {"--giz", s_success, "Giz:"},
-        {0}
+        {0, 0, 0}
     };
     test_cmdline("foo bar= baz? Giz", style, test_cases4);
 }
@@ -248,14 +242,14 @@ void test_short_options()
     test_case test_cases1[] = {
         {"-d d /bar", s_success, "-d: d /bar"},
         // This is treated as error when long options are disabled
-        {"--foo", s_long_not_allowed, ""},
+        {"--foo", s_success, "--foo"},
         {"-d13", s_extra_parameter, ""},
         {"-f14", s_success, "-f:14"},
         {"-g -f1", s_success, "-g: -f:1"},
         {"-f", s_missing_parameter, ""},
-        {0}
+        {0, 0, 0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases1);
+    test_cmdline(",d ,f= ,g", style, test_cases1);
 
     style = cmdline::style_t(
         allow_short | allow_dash_for_short
@@ -265,18 +259,11 @@ void test_short_options()
         {"-f 13", s_success, "-f:13"},
         {"-f -13", s_success, "-f:-13"},
         {"-f", s_missing_parameter, ""},
-        {"-f --foo", s_missing_parameter, ""},
         {"-f /foo", s_success, "-f:/foo"},
-        {"-f -d", s_success, "-f:-d"},
-        {"-g 13", s_success, "-g:13"},
-        {"-g", s_success, "-g:"},
-        {"-g --foo", s_long_not_allowed, "-g:"},
-        {"-g /foo", s_success, "-g:/foo"},
-        {"-g -d", s_success, "-g: -d:"},
-        {"-f12", s_short_adjacent_not_allowed, ""},
-        {0}
+        {"-f -d", s_missing_parameter, ""},
+        {0, 0, 0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases2);
+    test_cmdline(",d ,f=", style, test_cases2);
 
     style = cmdline::style_t(
         allow_short | short_allow_next
@@ -285,13 +272,10 @@ void test_short_options()
     test_case test_cases3[] = {
         {"-f10", s_success, "-f:10"},
         {"-f 10", s_success, "-f:10"},
-        {"-f -d", s_success, "-f:-d"},
-        {"-g10", s_success, "-g:10"},
-        {"-g 10", s_success, "-g:10"},
-        {"-g -d", s_success, "-g: -d:"},
-        {0}
+        {"-f -d", s_missing_parameter, ""},
+        {0, 0, 0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases3);
+    test_cmdline(",d ,f=", style, test_cases3);
 
     style = cmdline::style_t(
         allow_short | short_allow_next
@@ -300,14 +284,14 @@ void test_short_options()
 
     test_case test_cases4[] = {
         {"-de", s_success, "-d: -e:"},
-        {"-dg", s_success, "-d: -g:"},
-        {"-dg10", s_success, "-d: -g:10"},
-        {"-d12", s_extra_parameter, ""},
-        {"-gd", s_success, "-g:d"},
+        {"-df10", s_success, "-d: -f:10"},
+        // FIXME: review
+        //{"-d12", s_extra_parameter, ""},
+        {"-f12", s_success, "-f:12"},
         {"-fe", s_success, "-f:e"},
-        {0}
+        {0, 0, 0}
     };
-    test_cmdline(",d ,f= ,g? ,e", style, test_cases4);
+    test_cmdline(",d ,f= ,e", style, test_cases4);
 
 }
 
@@ -323,15 +307,13 @@ void test_dos_options()
 
     test_case test_cases1[] = {
         {"/d d -bar", s_success, "-d: d -bar"},
-        // This is treated as disallowed long option
-        {"--foo", s_long_not_allowed, ""},
+        {"--foo", s_success, "--foo"},
         {"/d13", s_extra_parameter, ""},
         {"/f14", s_success, "-f:14"},
-        {"/g /f1", s_success, "-g: -f:1"},
         {"/f", s_missing_parameter, ""},
-        {0}
+        {0, 0, 0}
     };
-    test_cmdline(",d ,f= ,g?", style, test_cases1);
+    test_cmdline(",d ,f=", style, test_cases1);
 
     style = cmdline::style_t(
         allow_short 
@@ -340,14 +322,14 @@ void test_dos_options()
 
     test_case test_cases2[] = {
         {"/de", s_extra_parameter, ""},
-        {"/gd", s_success, "-g:d"},
         {"/fe", s_success, "-f:e"},
-        {0}
+        {0, 0, 0}
     };
-    test_cmdline(",d ,f= ,g? ,e", style, test_cases2);
+    test_cmdline(",d ,f= ,e", style, test_cases2);
 
 }
 
+
 void test_disguised_long()
 {
     using namespace command_line_style;
@@ -363,7 +345,7 @@ void test_disguised_long()
         {"-foo -f", s_success, "foo: foo:"},
         {"-goo=x -gy", s_success, "goo:x goo:y"},
         {"-bee=x -by", s_success, "bee:x bee:y"},
-        {0}
+        {0, 0, 0}
     };
     test_cmdline("foo,f goo,g= bee,b?", style, test_cases1);
 
@@ -371,7 +353,7 @@ void test_disguised_long()
     test_case test_cases2[] = {
         {"/foo -f", s_success, "foo: foo:"},
         {"/goo=x", s_success, "goo:x"},
-        {0}
+        {0, 0, 0}
     };
     test_cmdline("foo,f goo,g= bee,b?", style, test_cases2);
 }
@@ -392,9 +374,18 @@ void test_guessing()
         {"--opt", s_ambiguous_option, ""},
         {"--f=1", s_success, "foo:1"},
         {"-far", s_success, "foo:ar"},
-        {0}
+        {0, 0, 0}
     };
     test_cmdline("opt123 opt56 foo,f=", style, test_cases1);
+
+    test_case test_cases2[] = { 
+        {"--fname file --fname2 file2", s_success, "fname: file fname2: file2"},
+        {"--fnam file --fnam file2", s_ambiguous_option, ""},
+        {"--fnam file --fname2 file2", s_ambiguous_option, ""},
+        {"--fname2 file2 --fnam file", s_ambiguous_option, ""},
+        {0, 0, 0} 
+    };
+    test_cmdline("fname fname2", style, test_cases2);
 }
 
 void test_arguments()
@@ -410,7 +401,7 @@ void test_arguments()
     test_case test_cases1[] = {
         {"-f file -gx file2", s_success, "-f: file -g:x file2"},
         {"-f - -gx - -- -e", s_success, "-f: - -g:x - -e"},
-        {0}
+        {0, 0, 0}
     };
     test_cmdline(",f ,g= ,e", style, test_cases1);
 
@@ -423,7 +414,7 @@ void test_arguments()
 
     test_case test_cases2[] = {
         {"-f - -gx - -- -e", s_success, "-f: - -g:x - -e"},
-        {0}
+        {0, 0, 0}
     };
     test_cmdline(",f ,g= ,e", style, test_cases2);
 }
@@ -441,49 +432,214 @@ void test_prefix()
 
     test_case test_cases1[] = {
         {"--foo.bar=12", s_success, "foo.bar:12"},
-        {0}
+        {0, 0, 0}
     };
 
     test_cmdline("foo*=", style, test_cases1);
 }
 
-void test_multiple()
+
+pair<string, string> at_option_parser(string const&s)
+{
+    if ('@' == s[0])
+        return std::make_pair(string("response-file"), s.substr(1));
+    else
+        return pair<string, string>();
+}
+
+pair<string, string> at_option_parser_broken(string const&s)
+{
+    if ('@' == s[0])
+        return std::make_pair(string("some garbage"), s.substr(1));
+    else
+        return pair<string, string>();
+}
+
+
+
+void test_additional_parser()
+{
+    options_description desc;
+    desc.add_options()
+        ("response-file", value<string>(), "response file")
+        ("foo", value<int>(), "foo")
+        ("bar,baz", value<int>(), "bar")
+        ;
+
+    vector<string> input;
+    input.push_back("@config");
+    input.push_back("--foo=1");
+    input.push_back("--baz=11");
+
+    cmdline cmd(input);
+    cmd.set_options_description(desc);
+    cmd.set_additional_parser(at_option_parser);
+
+    vector<option> result = cmd.run();
+
+    BOOST_REQUIRE(result.size() == 3);
+    BOOST_CHECK_EQUAL(result[0].string_key, "response-file");
+    BOOST_CHECK_EQUAL(result[0].value[0], "config");
+    BOOST_CHECK_EQUAL(result[1].string_key, "foo");
+    BOOST_CHECK_EQUAL(result[1].value[0], "1");    
+    BOOST_CHECK_EQUAL(result[2].string_key, "bar");
+    BOOST_CHECK_EQUAL(result[2].value[0], "11");
+
+    // Test that invalid options returned by additional style
+    // parser are detected.
+    cmdline cmd2(input);
+    cmd2.set_options_description(desc);
+    cmd2.set_additional_parser(at_option_parser_broken);
+
+    BOOST_CHECK_THROW(cmd2.run(), unknown_option);
+
+}
+
+vector<option> at_option_parser2(vector<string>& args)
+{
+    vector<option> result;
+    if ('@' == args[0][0]) {
+        // Simulate reading the response file.
+        result.push_back(option("foo", vector<string>(1, "1")));
+        result.push_back(option("bar", vector<string>(1, "1")));
+        args.erase(args.begin());
+    }
+    return result;
+}
+
+
+void test_style_parser()
+{
+    options_description desc;
+    desc.add_options()
+        ("foo", value<int>(), "foo")
+        ("bar", value<int>(), "bar")
+        ;
+
+    vector<string> input;
+    input.push_back("@config");
+
+    cmdline cmd(input);
+    cmd.set_options_description(desc);
+    cmd.extra_style_parser(at_option_parser2);
+
+    vector<option> result = cmd.run();
+
+    BOOST_REQUIRE(result.size() == 2);
+    BOOST_CHECK_EQUAL(result[0].string_key, "foo");
+    BOOST_CHECK_EQUAL(result[0].value[0], "1");    
+    BOOST_CHECK_EQUAL(result[1].string_key, "bar");
+    BOOST_CHECK_EQUAL(result[1].value[0], "1");    
+}
+
+void test_unregistered()
+{
+    // Check unregisted option when no options are registed at all.
+    options_description desc;
+
+    vector<string> input;
+    input.push_back("--foo=1");
+    input.push_back("--bar");
+    input.push_back("1");
+    input.push_back("-b");
+    input.push_back("-biz");
+
+    cmdline cmd(input);
+    cmd.set_options_description(desc);
+    cmd.allow_unregistered();
+    
+    vector<option> result = cmd.run();
+    BOOST_REQUIRE(result.size() == 5);
+    // --foo=1
+    BOOST_CHECK_EQUAL(result[0].string_key, "foo");
+    BOOST_CHECK_EQUAL(result[0].unregistered, true);
+    BOOST_CHECK_EQUAL(result[0].value[0], "1");
+    // --bar
+    BOOST_CHECK_EQUAL(result[1].string_key, "bar");
+    BOOST_CHECK_EQUAL(result[1].unregistered, true);
+    BOOST_CHECK(result[1].value.empty());
+    // '1' is considered a positional option, not a value to
+    // --bar
+    BOOST_CHECK(result[2].string_key.empty());
+    BOOST_CHECK(result[2].position_key == 0);
+    BOOST_CHECK_EQUAL(result[2].unregistered, false);
+    BOOST_CHECK_EQUAL(result[2].value[0], "1");
+    // -b
+    BOOST_CHECK_EQUAL(result[3].string_key, "-b");
+    BOOST_CHECK_EQUAL(result[3].unregistered, true);
+    BOOST_CHECK(result[3].value.empty());
+    // -biz
+    BOOST_CHECK_EQUAL(result[4].string_key, "-b");
+    BOOST_CHECK_EQUAL(result[4].unregistered, true);
+    BOOST_CHECK_EQUAL(result[4].value[0], "iz");
+
+    // Check sticky short options together with unregisted options.
+    
+    desc.add_options()
+        ("help,h", "")
+        ("magic,m", value<string>(), "")
+        ;
+
+    input.clear();
+    input.push_back("-hc");
+    input.push_back("-mc");
+
+
+    cmdline cmd2(input);
+    cmd2.set_options_description(desc);
+    cmd2.allow_unregistered();
+    
+    result = cmd2.run();
+
+    BOOST_REQUIRE(result.size() == 3);
+    BOOST_CHECK_EQUAL(result[0].string_key, "help");
+    BOOST_CHECK_EQUAL(result[0].unregistered, false);
+    BOOST_CHECK(result[0].value.empty());
+    BOOST_CHECK_EQUAL(result[1].string_key, "-c");
+    BOOST_CHECK_EQUAL(result[1].unregistered, true);
+    BOOST_CHECK(result[1].value.empty());
+    BOOST_CHECK_EQUAL(result[2].string_key, "magic");
+    BOOST_CHECK_EQUAL(result[2].unregistered, false);
+    BOOST_CHECK_EQUAL(result[2].value[0], "c");
+
+    // CONSIDER:
+    // There's a corner case:
+    //   -foo
+    // when 'allow_long_disguise' is set. Should this be considered
+    // disguised long option 'foo' or short option '-f' with value 'oo'?
+    // It's not clear yet, so I'm leaving the decision till later.
+}
+
+void test_implicit_value()
 {
     using namespace command_line_style;
     cmdline::style_t style;
 
     style = cmdline::style_t(
-        unix_style | long_allow_next);
+        allow_long | long_allow_adjacent
+        );
 
     test_case test_cases1[] = {
-        {"--value 1 2 3 4 --help", s_success, "value:1-2-3-4 help:"},
-        {"--value 1 2 3 4 --", s_success, "value:1-2-3-4"},
-        {0}
+        // 'bar' does not even look like option, so is consumed
+        {"--foo bar", s_success, "foo:bar"},
+        // '--bar' looks like option, and such option exists, so we don't consume this token
+        {"--foo --bar", s_success, "foo: bar:"},
+        // '--biz' looks like option, but does not match any existing one.
+        // Presently this results in parse error, since
+        // (1) in cmdline.cpp:finish_option, we only consume following tokens if they are
+        // requires
+        // (2) in cmdline.cpp:run, we let options consume following positional options
+        // For --biz, an exception is thrown between 1 and 2.
+        // We might want to fix that in future.
+        {"--foo --biz", s_unknown_option, ""},
+        {0, 0, 0}
     };
 
-    test_cmdline("value+ help", style, test_cases1);
+    test_cmdline("foo? bar?", style, test_cases1);
 }
 
-void test_style_errors()
+int main(int /*ac*/, char** /*av*/)
 {
-    using namespace command_line_style;
-    char* argv[] = {"program"};
-
-    BOOST_CHECK_THROW(cmdline cmd(1, (const char*const *)argv, allow_long),
-                      invalid_command_line_style);
-
-    BOOST_CHECK_THROW(cmdline cmd(1, (const char*const *)argv, allow_short),
-                      invalid_command_line_style);
-
-    BOOST_CHECK_THROW(cmdline cmd(1, (const char*const *)argv, allow_short | 
-                                  short_allow_next),
-                      invalid_command_line_style);
-}
-
-int test_main(int ac, char* av[])
-{
-// ###     detail::test_cmdline_detail();
-
     test_long_options();
     test_short_options();
     test_dos_options();
@@ -491,31 +647,10 @@ int test_main(int ac, char* av[])
     test_guessing();
     test_arguments();
     test_prefix();
-    test_multiple();
-    test_style_errors();
-
-    cmdline cmd((int)ac, (const char*const *)av, 
-                int(command_line_style::unix_style));
-    cmd.add_option("version", 'v');
-    cmd.add_option("help", 'h');
-    cmd.add_option("verbose", 'V');
-    cmd.add_option("magic", 'm');
-    cmd.add_option("output", 'o', ':');
-
-    try {
-        while(++cmd) {
-
-            if (cmd.at_argument()) {
-                cout << "Argument : " << cmd.argument() << "\n";
-            } else {
-                cout << "Option : " << cmd.option_name()
-                     << "(" << cmd.option_value() << ")\n";
-            } 
-        }
-    }
-    catch(exception& e) {
-        cout << e.what() << "\n";
-    }
+    test_additional_parser();
+    test_style_parser();
+    test_unregistered();
+    test_implicit_value();
 
     return 0;
 }

test/config_test.cfg

@@ -0,0 +1,9 @@
+gv1 = 0#asd
+empty_value = 
+plug3 = 7
+b = true
+
+[m1]
+v1 = 1
+v2 = 2
+v3 = 3

test/exception_test.cpp

@@ -0,0 +1,264 @@
+// Copyright Sascha Ochsenknecht 2009.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+
+#include <boost/program_options/parsers.hpp>
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/variables_map.hpp>
+#include <boost/program_options/cmdline.hpp>
+using namespace boost::program_options;
+
+#include <iostream>
+#include <sstream>
+#include <vector>
+#include <cassert>
+using namespace std;
+
+#include "minitest.hpp"
+
+
+void test_ambiguous() 
+{
+    options_description desc; 
+    desc.add_options()
+        ("cfgfile,c", value<string>()->multitoken(), "the config file") 
+        ("output,c", value<string>(), "the output file") 
+        ("output,o", value<string>(), "the output file")
+    ;
+
+    const char* cmdline[] = {"program", "-c", "file", "-o", "anotherfile"};
+
+    variables_map vm;
+    try {
+       store(parse_command_line(sizeof(cmdline)/sizeof(const char*), 
+                                    const_cast<char**>(cmdline), desc), vm);
+    }
+    catch (ambiguous_option& e)
+    {
+        BOOST_CHECK_EQUAL(e.alternatives().size(), 2);
+        BOOST_CHECK_EQUAL(e.get_option_name(), "-c");      
+        BOOST_CHECK_EQUAL(e.alternatives()[0], "cfgfile");
+        BOOST_CHECK_EQUAL(e.alternatives()[1], "output");
+    }
+}
+
+
+void test_ambiguous_long()
+{
+    options_description desc;
+    desc.add_options()
+        ("cfgfile,c", value<string>()->multitoken(), "the config file")
+        ("output,c", value<string>(), "the output file")
+        ("output,o", value<string>(), "the output file")
+    ;
+
+    const char* cmdline[] = {"program", "--cfgfile", "file", "--output", "anotherfile"};
+
+    variables_map vm;
+    try {
+       store(parse_command_line(sizeof(cmdline)/sizeof(const char*),
+                                    const_cast<char**>(cmdline), desc), vm);
+    }
+    catch (ambiguous_option& e)
+    {
+        BOOST_CHECK_EQUAL(e.alternatives().size(), 2);
+        BOOST_CHECK_EQUAL(e.get_option_name(), "--output");
+        BOOST_CHECK_EQUAL(e.alternatives()[0], "output");
+        BOOST_CHECK_EQUAL(e.alternatives()[1], "output");
+    }
+}
+
+void test_ambiguous_multiple_long_names()
+{
+    options_description desc;
+    desc.add_options()
+        ("cfgfile,foo,c", value<string>()->multitoken(), "the config file")
+        ("output,foo,o", value<string>(), "the output file")
+    ;
+
+    const char* cmdline[] = {"program", "--foo", "file"};
+
+    variables_map vm;
+    try {
+       store(parse_command_line(sizeof(cmdline)/sizeof(const char*),
+                                    const_cast<char**>(cmdline), desc), vm);
+    }
+    catch (ambiguous_option& e)
+    {
+        BOOST_CHECK_EQUAL(e.alternatives().size(), 2);
+        BOOST_CHECK_EQUAL(e.get_option_name(), "--foo");
+        BOOST_CHECK_EQUAL(e.alternatives()[0], "cfgfile");
+        BOOST_CHECK_EQUAL(e.alternatives()[1], "output");
+    }
+}
+
+
+
+void test_unknown_option() 
+{
+   options_description desc;
+   desc.add_options()
+        ("cfgfile,c", value<string>(), "the configfile")
+      ;
+
+   const char* cmdline[] = {"program", "-c", "file", "-f", "anotherfile"};
+   
+   variables_map vm;
+   try {
+      store(parse_command_line(sizeof(cmdline)/sizeof(const char*), 
+                                    const_cast<char**>(cmdline), desc), vm);
+   }
+   catch (unknown_option& e)
+   {
+      BOOST_CHECK_EQUAL(e.get_option_name(), "-f");      
+      BOOST_CHECK_EQUAL(string(e.what()), "unrecognised option '-f'");
+   }
+}
+
+
+
+void test_multiple_values() 
+{
+   options_description desc;
+   desc.add_options()
+        ("cfgfile,c", value<string>()->multitoken(), "the config file")
+        ("output,o", value<string>(), "the output file")
+      ;
+
+   const char* cmdline[] = { "program", "-o", "fritz", "hugo", "--cfgfile", "file", "c", "-o", "text.out" };
+   
+   variables_map vm;
+   try {
+      store(parse_command_line(sizeof(cmdline)/sizeof(const char*), 
+                                    const_cast<char**>(cmdline), desc), vm);
+      notify(vm);
+   }
+   catch (validation_error& e)
+   {
+      // TODO: this is currently validation_error, shouldn't it be multiple_values ???
+      // 
+      //   multiple_values is thrown only at one place untyped_value::xparse(),
+      //    but I think this can never be reached
+      //   because: untyped_value always has one value and this is filtered before reach specific
+      //   validation and parsing
+      //
+      BOOST_CHECK_EQUAL(e.get_option_name(), "--cfgfile");      
+      BOOST_CHECK_EQUAL(string(e.what()), "option '--cfgfile' only takes a single argument");
+   }
+}
+
+
+void test_multiple_occurrences()
+{
+   options_description desc;
+   desc.add_options()
+        ("cfgfile,c", value<string>(), "the configfile")
+      ;
+
+   const char* cmdline[] = {"program", "--cfgfile", "file", "-c", "anotherfile"};
+
+   variables_map vm;
+   try {
+      store(parse_command_line(sizeof(cmdline)/sizeof(const char*),
+                                    const_cast<char**>(cmdline), desc), vm);
+      notify(vm);
+   }
+   catch (multiple_occurrences& e)
+   {
+      BOOST_CHECK_EQUAL(e.get_option_name(), "--cfgfile");
+      BOOST_CHECK_EQUAL(string(e.what()), "option '--cfgfile' cannot be specified more than once");
+   }
+}
+
+void test_multiple_occurrences_with_different_names()
+{
+   options_description desc;
+   desc.add_options()
+        ("cfgfile,config-file,c", value<string>(), "the configfile")
+      ;
+
+   const char* cmdline[] = {"program", "--config-file", "file", "--cfgfile", "anotherfile"};
+
+   variables_map vm;
+   try {
+      store(parse_command_line(sizeof(cmdline)/sizeof(const char*),
+                                    const_cast<char**>(cmdline), desc), vm);
+      notify(vm);
+   }
+   catch (multiple_occurrences& e)
+   {
+      BOOST_CHECK( (e.get_option_name() == "--cfgfile") || (e.get_option_name() == "--config-file"));
+      BOOST_CHECK(
+         (string(e.what()) == "option '--cfgfile' cannot be specified more than once") ||
+         (string(e.what()) == "option '--config-file' cannot be specified more than once")
+      );
+   }
+}
+
+
+void test_multiple_occurrences_with_non_key_names()
+{
+   options_description desc;
+   desc.add_options()
+        ("cfgfile,config-file,c", value<string>(), "the configfile")
+      ;
+
+   const char* cmdline[] = {"program", "--config-file", "file", "-c", "anotherfile"};
+
+   variables_map vm;
+   try {
+      store(parse_command_line(sizeof(cmdline)/sizeof(const char*),
+                                    const_cast<char**>(cmdline), desc), vm);
+      notify(vm);
+   }
+   catch (multiple_occurrences& e)
+   {
+       BOOST_CHECK_EQUAL(e.get_option_name(), "--cfgfile");
+       BOOST_CHECK_EQUAL(string(e.what()), "option '--cfgfile' cannot be specified more than once");
+   }
+}
+
+
+void test_missing_value()
+{
+    options_description desc;
+    desc.add_options()
+        ("cfgfile,c", value<string>()->multitoken(), "the config file") 
+        ("output,o", value<string>(), "the output file")
+    ;
+    // missing value for option '-c'
+    const char* cmdline[] = { "program", "-c", "-c", "output.txt"};
+    
+    variables_map vm;
+    
+    try {
+      store(parse_command_line(sizeof(cmdline)/sizeof(const char*), 
+                                       const_cast<char**>(cmdline), desc), vm);
+      notify(vm);
+   } 
+   catch (invalid_command_line_syntax& e)
+   {
+      BOOST_CHECK_EQUAL(e.kind(), invalid_syntax::missing_parameter);
+      BOOST_CHECK_EQUAL(e.tokens(), "--cfgfile");
+   }
+}
+
+
+
+int main(int /*ac*/, char** /*av*/)
+{
+   test_ambiguous();
+   test_ambiguous_long();
+   test_ambiguous_multiple_long_names();
+   test_unknown_option();
+   test_multiple_values();
+   test_multiple_occurrences();
+   test_multiple_occurrences_with_different_names();
+   test_multiple_occurrences_with_non_key_names();
+   test_missing_value();
+
+   return 0;
+}
+

test/exception_txt_test.cpp

@@ -0,0 +1,693 @@
+// Copyright Leo Goodstadt 2012
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+
+#include <boost/program_options/parsers.hpp>
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/variables_map.hpp>
+#include <boost/program_options/cmdline.hpp>
+using namespace boost::program_options;
+
+#include <iostream>
+#include <sstream>
+#include <vector>
+#include <cassert>
+using namespace std;
+
+#include "minitest.hpp"
+
+
+
+// 
+//  like BOOST_CHECK_EQUAL but with more descriptive error message
+//
+#define CHECK_EQUAL(description, a, b) if (a != b) {std::cerr << "\n\nError:\n<<" << \
+        description << ">>\n  Expected text=\"" << b << "\"\n  Actual text  =\"" << a << "\"\n\n"; assert(a == b);}
+
+
+// Uncomment for Debugging, removes asserts so we can see more failures!
+//#define BOOST_ERROR(description) std::cerr << description; std::cerr << "\n"; 
+
+
+//8888888888888888888888888888888888888888888888888888888888888888888888888888888888888888
+// 
+//  Uncomment to print out the complete set of diagnostic messages for the different test cases
+/*
+#define CHECK_EQUAL(description, a, b) if (a != b) {std::cerr << "\n\nError:  " << \
+    description << "\n  Expecting\n" << b << "\n  Found\n" << a << "\n\n"; } \
+    else {std::cout << description<< "\t" << b << "\n";}
+*/ 
+
+//8888888888888888888888888888888888888888888888888888888888888888888888888888888888888888
+
+
+// 
+//  test exception for each specified command line style, e.g. short dash or config file
+//
+template<typename EXCEPTION>
+void test_each_exception_message(const string& test_description, const vector<const char*>& argv, options_description& desc, int style, string exception_msg, istream& is = cin)
+{
+    if (exception_msg.length() == 0)
+        return;
+    variables_map vm;
+    unsigned argc = argv.size();
+
+
+    try {
+        if (style == -1)
+            store(parse_config_file(is, desc), vm);
+        else
+            store(parse_command_line(argv.size(), &argv[0], desc, style), vm);
+        notify(vm);    
+    } 
+    catch (EXCEPTION& e)
+    {
+       //cerr << "Correct:\n\t" << e.what() << "\n";
+       CHECK_EQUAL(test_description, e.what(), exception_msg);
+       return;
+    }
+    catch (std::exception& e)
+    {
+        // concatenate argv without boost::algorithm::join
+        string argv_txt;
+        for (unsigned ii = 0; ii < argc - 1; ++ii)
+            argv_txt += argv[ii] + string(" ");
+        if (argc)
+            argv_txt += argv[argc - 1];
+
+       BOOST_ERROR("\n<<" + test_description + 
+                    string(">>\n  Unexpected exception type!\n  Actual text  =\"") + e.what() + 
+                    "\"\n  argv         =\"" + argv_txt +
+                    "\"\n  Expected text=\"" + exception_msg + "\"\n");
+       return;
+    }
+    BOOST_ERROR(test_description + ": No exception thrown. ");
+}
+
+
+
+
+// 
+//  test exception messages for all command line styles (unix/long/short/slash/config file)
+//
+//      try each command line style in turn
+const int unix_style = command_line_style::unix_style;
+const int short_dash = command_line_style::allow_dash_for_short | command_line_style::allow_short | command_line_style::short_allow_adjacent | command_line_style::allow_sticky;
+const int short_slash = command_line_style::allow_slash_for_short | command_line_style::allow_short | command_line_style::short_allow_adjacent;
+const int long_dash = command_line_style::allow_long | command_line_style::long_allow_adjacent | command_line_style::allow_guessing;
+
+
+
+template<typename EXCEPTION>
+void test_exception_message(const vector<vector<const char*> >& argv,
+                            options_description& desc,
+                            const string& error_description, 
+                            const char* expected_message_template[5])
+{
+    string expected_message;
+
+    // unix
+    expected_message = expected_message_template[0];
+    test_each_exception_message<EXCEPTION>(error_description + " -- unix", 
+                                  argv[0], desc, unix_style, expected_message);
+
+    // long dash only
+    expected_message = expected_message_template[1];
+    test_each_exception_message<EXCEPTION>(error_description + " -- long_dash", 
+                                  argv[1], desc, long_dash, expected_message);
+
+
+    // short dash only
+    expected_message = expected_message_template[2];
+    test_each_exception_message<EXCEPTION>(error_description + " -- short_dash", 
+                                  argv[2], desc, short_dash, expected_message);
+
+    // short slash only
+    expected_message = expected_message_template[3];
+    test_each_exception_message<EXCEPTION>(error_description + " -- short_slash", 
+                                  argv[3], desc, short_slash, expected_message);
+
+    // config file only
+    expected_message = expected_message_template[4];
+    if (expected_message.length())
+    {
+        istringstream istrm(argv[4][0]);
+        test_each_exception_message<EXCEPTION>(error_description + " -- config_file", 
+                                          argv[4], desc, -1, expected_message, istrm);
+    }
+
+}
+
+#define VEC_STR_PUSH_BACK(vec, c_array)  \
+    vec.push_back(vector<const char*>(c_array, c_array + sizeof(c_array) / sizeof(char*)));
+
+//________________________________________________________________________________________
+// 
+//  invalid_option_value
+//
+//________________________________________________________________________________________
+void test_invalid_option_value_exception_msg()
+{
+    options_description desc;
+    desc.add_options()
+        ("int-option,d", value< int >(),	"An option taking an integer")
+    ;
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = { "program", "-d", "A_STRING"}   ;  VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = { "program", "--int", "A_STRING"};  VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = { "program", "-d", "A_STRING"}   ;  VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = { "program", "/d", "A_STRING"}   ;  VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "int-option=A_STRING"}         ;  VEC_STR_PUSH_BACK(argv, argv4); 
+
+    const char* expected_msg[5] = {
+                                "the argument ('A_STRING') for option '--int-option' is invalid", 
+                                "the argument ('A_STRING') for option '--int-option' is invalid", 
+                                "the argument ('A_STRING') for option '-d' is invalid", 
+                                "the argument ('A_STRING') for option '/d' is invalid", 
+                                "the argument ('A_STRING') for option 'int-option' is invalid",
+    };
+
+
+    test_exception_message<invalid_option_value>(argv, desc, "invalid_option_value",
+                                                 expected_msg);
+
+
+}
+
+//________________________________________________________________________________________
+// 
+//  missing_value
+//
+//________________________________________________________________________________________
+void test_missing_value_exception_msg()
+{
+    options_description desc;
+    desc.add_options()
+        ("cfgfile,e", value<string>(), "the config file") 
+        ("output,o", value<string>(), "the output file")
+    ;
+    vector<vector<const char*> > argv;
+    const char* argv0[] = { "program", "-e", "-e", "output.txt"} ; VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = { "program", "--cfgfile"}              ; VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = { "program", "-e", "-e", "output.txt"} ; VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = { "program", "/e", "/e", "output.txt"} ; VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { ""}    ;      VEC_STR_PUSH_BACK(argv, argv4); 
+
+    const char* expected_msg[5] = {
+                                "the required argument for option '--cfgfile' is missing",
+                                "the required argument for option '--cfgfile' is missing",
+                                "the required argument for option '-e' is missing",
+                                "", // Ignore probable bug in cmdline::finish_option
+                                    //"the required argument for option '/e' is missing",
+                                "",
+    };
+    test_exception_message<invalid_command_line_syntax>(argv, desc, 
+                                                        "invalid_syntax::missing_parameter", 
+                                                        expected_msg);
+}
+
+//________________________________________________________________________________________
+// 
+//  ambiguous_option
+//
+//________________________________________________________________________________________
+void test_ambiguous_option_exception_msg()
+{
+    options_description desc; 
+    desc.add_options()
+        ("cfgfile1,c", value<string>(), "the config file") 
+        ("cfgfile2,o",  value<string>(), "the config file") 
+        ("good,g",                          "good option") 
+        ("output,c",   value<string>(), "the output file") 
+        ("output",     value<string>(), "the output file") 
+    ;
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = {"program", "-ggc", "file", "-o", "anotherfile"}             ; VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = {"program", "--cfgfile", "file", "--cfgfile", "anotherfile"} ; VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = {"program", "-ggc", "file", "-o", "anotherfile"}             ; VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = {"program", "/c", "file", "/o", "anotherfile"}               ; VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "output=output.txt\n"}                                     ; VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {
+                                "option '-c' is ambiguous and matches '--cfgfile1', and '--output'",
+                                "option '--cfgfile' is ambiguous and matches '--cfgfile1', and '--cfgfile2'",
+                                "option '-c' is ambiguous",
+                                "option '/c' is ambiguous",
+                                "option 'output' is ambiguous and matches different versions of 'output'",
+    };
+    test_exception_message<ambiguous_option>(argv, desc, "ambiguous_option",
+                                             expected_msg);
+}
+
+//________________________________________________________________________________________
+// 
+//  multiple_occurrences
+//
+//________________________________________________________________________________________
+void test_multiple_occurrences_exception_msg()
+{
+    options_description desc; 
+    desc.add_options()
+                ("cfgfile,c", value<string>(), "the configfile")
+    ;
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = {"program", "-c", "file", "-c", "anotherfile"}           ; VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = {"program", "--cfgfi", "file", "--cfgfi", "anotherfile"} ; VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = {"program", "-c", "file", "-c", "anotherfile"}           ; VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = {"program", "/c", "file", "/c", "anotherfile"}           ; VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "cfgfile=output.txt\ncfgfile=output.txt\n"}            ; VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {
+                                "option '--cfgfile' cannot be specified more than once",
+                                "option '--cfgfile' cannot be specified more than once",
+                                "option '-c' cannot be specified more than once",
+                                "option '/c' cannot be specified more than once",
+                                "option 'cfgfile' cannot be specified more than once",
+    };
+    test_exception_message<multiple_occurrences>(argv, desc, "multiple_occurrences",
+                                                expected_msg);
+}
+
+//________________________________________________________________________________________
+// 
+//  unknown_option
+//
+//________________________________________________________________________________________
+void test_unknown_option_exception_msg()
+{
+    options_description desc; 
+    desc.add_options()
+        ("good,g",                          "good option") 
+    ;
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = {"program", "-ggc", "file"}      ; VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = {"program", "--cfgfile", "file"} ; VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = {"program", "-ggc", "file"}      ; VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = {"program", "/c", "file"}        ; VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "cfgfile=output.txt\n"}        ; VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {
+                                "unrecognised option '-ggc'",
+                                "unrecognised option '--cfgfile'",
+                                "unrecognised option '-ggc'",
+                                "unrecognised option '/c'",
+                                "unrecognised option 'cfgfile'",
+    };
+    test_exception_message<unknown_option>(argv, desc, "unknown_option", expected_msg);
+}
+
+//________________________________________________________________________________________
+// 
+//  validation_error::invalid_bool_value
+//
+//________________________________________________________________________________________
+void test_invalid_bool_value_exception_msg()
+{
+    options_description desc; 
+    desc.add_options()
+        ("bool_option,b",	value< bool>(),	"bool_option")
+        ;
+
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = {"program", "-b", "file"}           ; VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = {"program", "--bool_optio", "file"} ; VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = {"program", "-b", "file"}           ; VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = {"program", "/b", "file"}           ; VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "bool_option=output.txt\n"}       ; VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {                               
+                                "the argument ('file') for option '--bool_option' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'",
+                                "the argument ('file') for option '--bool_option' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'",
+                                "the argument ('file') for option '-b' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'",
+                                "the argument ('file') for option '/b' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'",
+                                "the argument ('output.txt') for option 'bool_option' is invalid. Valid choices are 'on|off', 'yes|no', '1|0' and 'true|false'",
+    };
+    test_exception_message<validation_error>(argv, 
+                                desc,
+                                "validation_error::invalid_bool_value",
+                                expected_msg);
+}
+
+
+
+
+//________________________________________________________________________________________
+// 
+//  validation_error::multiple_values_not_allowed
+//
+//________________________________________________________________________________________
+//
+//  Strange exception: sole purpose seems to be catching multitoken() associated with a scalar
+//  validation_error::multiple_values_not_allowed seems thus to be a programmer error
+//  
+//
+void test_multiple_values_not_allowed_exception_msg()
+{
+    options_description desc; 
+    desc.add_options()
+         ("cfgfile,c", value<string>()->multitoken(), "the config file")
+         ("good,g",                                     "good option")
+         ("output,o", value<string>(),                  "the output file")
+       ;
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = { "program", "-c", "file", "c", "-o", "fritz", "hugo" }              ;      VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = { "program", "--cfgfil", "file", "c", "--outpu", "fritz", "hugo" }   ;      VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = { "program", "-c", "file", "c", "-o", "fritz", "hugo"}               ;      VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = { "program", "/c", "file", "c", "/o", "fritz", "hugo"}               ;      VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "" }                                                               ;      VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {                               
+                                "option '--cfgfile' only takes a single argument",
+                                "option '--cfgfile' only takes a single argument",
+                                "option '-c' only takes a single argument",
+                                "option '/c' only takes a single argument",
+                                "",
+    };
+    test_exception_message<validation_error>(argv, 
+                                desc,
+                                "validation_error::multiple_values_not_allowed",
+                                expected_msg);
+}
+
+//________________________________________________________________________________________
+// 
+//  validation_error::at_least_one_value_required
+//
+//________________________________________________________________________________________
+//
+//  Strange exception: sole purpose seems to be catching zero_tokens() associated with a scalar
+//  validation_error::multiple_values_not_allowed seems thus to be a programmer error
+//  
+//
+void test_at_least_one_value_required_exception_msg()
+{
+
+
+    options_description desc; 
+    desc.add_options()
+         ("cfgfile,c", value<int>()->zero_tokens(), "the config file")
+         ("other,o", value<string>(), "other")
+       ;
+
+    vector<vector<const char*> > argv;
+    const char* argv0[] = { "program", "-c"                       }  ;      VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = { "program", "--cfg", "--o", "name"     }  ;      VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = { "program", "-c"   , "-o"   , "name"   }  ;      VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = { "program", "/c"                       }  ;      VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { ""                                    }  ;      VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {                               
+                                "option '--cfgfile' requires at least one argument",
+                                "option '--cfgfile' requires at least one argument",
+                                "option '-c' requires at least one argument",
+                                "option '/c' requires at least one argument",
+                                "",
+    };
+    test_exception_message<validation_error>(argv, 
+                                desc,
+                                "validation_error::at_least_one_value_required",
+                                expected_msg);
+}
+
+
+//________________________________________________________________________________________
+// 
+//  required_option
+//
+//________________________________________________________________________________________
+void test_required_option_exception_msg()
+{
+    options_description desc; 
+    desc.add_options()
+         ("cfgfile,c", value<string>()->required(), "the config file")
+         ("good,g",                                 "good option")
+         ("output,o", value<string>()->required(),  "the output file")
+       ;
+
+    vector<vector<const char*> > argv;            
+    const char* argv0[] = { "program", "-g" }    ;      VEC_STR_PUSH_BACK(argv, argv0);
+    const char* argv1[] = { "program", "--g" }   ;      VEC_STR_PUSH_BACK(argv, argv1); 
+    const char* argv2[] = { "program", "-g"}     ;      VEC_STR_PUSH_BACK(argv, argv2);
+    const char* argv3[] = { "program", "/g"}     ;      VEC_STR_PUSH_BACK(argv, argv3); 
+    const char* argv4[] = { "" }                 ;      VEC_STR_PUSH_BACK(argv, argv4); 
+    const char* expected_msg[5] = {                               
+                                "the option '--cfgfile' is required but missing",
+                                "the option '--cfgfile' is required but missing",
+                                "the option '-c' is required but missing",
+                                "the option '/c' is required but missing",
+                                "the option 'cfgfile' is required but missing",
+    };
+    test_exception_message<required_option>(argv, 
+                                desc,
+                                "required_option",
+                                expected_msg);
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/** 
+ * Check if this is the expected exception with the right message is being thrown inside 
+ * func 
+*/
+template <typename EXCEPTION, typename FUNC>
+void test_exception(const string& test_name, const string& exception_txt, FUNC func)
+{
+
+    try {
+        options_description desc; 
+        variables_map vm;
+        func(desc, vm);
+    } 
+    catch (EXCEPTION& e)
+    {
+       CHECK_EQUAL(test_name, e.what(), exception_txt);
+       return;
+    }
+    catch (std::exception& e)
+    {
+       BOOST_ERROR(string(test_name + ":\nUnexpected exception. ") + e.what() + 
+                   "\nExpected text:\n" + exception_txt + "\n\n");
+       return;
+    }
+    BOOST_ERROR(test_name + ": No exception thrown. ");
+}
+
+
+
+//________________________________________________________________________________________
+// 
+//  check_reading_file
+//
+//________________________________________________________________________________________
+void check_reading_file(options_description& desc, variables_map& vm)
+{
+    desc.add_options()
+         ("output,o", value<string>(), "the output file");
+    
+    const char* file_name = "no_such_file";
+    store(parse_config_file<char>(file_name, desc, true), vm);
+
+}
+
+
+//________________________________________________________________________________________
+// 
+//  config_file_wildcard
+//
+//________________________________________________________________________________________
+void config_file_wildcard(options_description& desc, variables_map& vm)
+{
+    desc.add_options()
+         ("outpu*", value<string>(), "the output file1")
+         ("outp*",    value<string>(), "the output file2")
+       ;
+    istringstream is("output1=whichone\noutput2=whichone\n");
+    store(parse_config_file(is, desc), vm);
+}
+
+//________________________________________________________________________________________
+// 
+//  invalid_syntax::unrecognized_line
+//
+//________________________________________________________________________________________
+void unrecognized_line(options_description& desc, variables_map& vm)
+{
+    istringstream is("funny wierd line\n");
+    store(parse_config_file(is, desc), vm);
+}
+
+//________________________________________________________________________________________
+// 
+//  abbreviated_options_in_config_file
+//
+//________________________________________________________________________________________
+void abbreviated_options_in_config_file(options_description& desc, variables_map& vm)
+{
+    desc.add_options()(",o", value<string>(), "the output file");
+    istringstream is("o=output.txt\n");
+    store(parse_config_file(is, desc), vm);
+}
+
+
+//________________________________________________________________________________________
+// 
+//  too_many_positional_options
+//
+//________________________________________________________________________________________
+void too_many_positional_options(options_description& desc, variables_map& vm)
+{
+    const char* argv[] = {"program", "1", "2", "3"};
+    positional_options_description positional_args;
+    positional_args.add("two_positional_arguments", 2);
+    store(command_line_parser(4, argv).options(desc).positional(positional_args).run(), vm);
+}
+
+
+//________________________________________________________________________________________
+// 
+//  invalid_command_line_style
+//
+//________________________________________________________________________________________
+
+void test_invalid_command_line_style_exception_msg()
+{
+    string test_name = "invalid_command_line_style";
+    using namespace command_line_style;
+    options_description desc; 
+    desc.add_options()("output,o", value<string>(), "the output file");
+
+    vector<int> invalid_styles;
+    invalid_styles.push_back(allow_short | short_allow_adjacent);
+    invalid_styles.push_back(allow_short | allow_dash_for_short);
+    invalid_styles.push_back(allow_long);
+    vector<string> invalid_diagnostics;
+    invalid_diagnostics.push_back("boost::program_options misconfiguration: choose one "
+                                  "or other of 'command_line_style::allow_slash_for_short' "
+                                  "(slashes) or 'command_line_style::allow_dash_for_short' "
+                                  "(dashes) for short options.");
+    invalid_diagnostics.push_back("boost::program_options misconfiguration: choose one "
+                                  "or other of 'command_line_style::short_allow_next' "
+                                  "(whitespace separated arguments) or "
+                                  "'command_line_style::short_allow_adjacent' ('=' "
+                                  "separated arguments) for short options.");
+    invalid_diagnostics.push_back("boost::program_options misconfiguration: choose one "
+                                  "or other of 'command_line_style::long_allow_next' "
+                                  "(whitespace separated arguments) or "
+                                  "'command_line_style::long_allow_adjacent' ('=' "
+                                  "separated arguments) for long options.");
+
+
+    const char* argv[] = {"program"};
+    variables_map vm;
+    for (unsigned ii = 0; ii < 3; ++ii)
+    {
+        bool exception_thrown = false;
+        try
+        {
+            store(parse_command_line(1, argv, desc, invalid_styles[ii]), vm);
+        }
+        catch (invalid_command_line_style& e)
+        {
+           string error_msg("arguments are not allowed for unabbreviated option names");
+           CHECK_EQUAL(test_name, e.what(), invalid_diagnostics[ii]);
+           exception_thrown = true;
+        }
+        catch (std::exception& e)
+        {
+           BOOST_ERROR(string(test_name + ":\nUnexpected exception. ") + e.what() + 
+                            "\nExpected text:\n" + invalid_diagnostics[ii] + "\n");
+           exception_thrown = true;
+        }
+        if (!exception_thrown)
+        {
+            BOOST_ERROR(test_name << ": No exception thrown. ");
+        }
+    }
+}
+
+void test_empty_value_inner(options_description &opts, variables_map& vm) {
+    positional_options_description popts;
+    opts.add_options()("foo", value<uint32_t>()->value_name("<time>")->required());
+    popts.add("foo", 1);
+    vector<string> tokens(1, "");
+    parsed_options parsed = command_line_parser(tokens)
+        .style(command_line_style::default_style & ~command_line_style::allow_guessing)
+        .options(opts)
+        .positional(popts)
+        .run();
+    store(parsed, vm);
+}
+
+void test_empty_value() {
+    // Test that passing empty token for an option that requires integer does not result
+    // in out-of-range error in error reporting code.
+    test_exception<invalid_option_value>(
+        "test_empty_value",
+        "the argument for option '--foo' is invalid",
+        test_empty_value_inner);
+}
+
+int main(int /*ac*/, char** /*av*/)
+{
+   test_ambiguous_option_exception_msg();
+   test_unknown_option_exception_msg();
+   test_multiple_occurrences_exception_msg();
+   test_missing_value_exception_msg();
+   test_invalid_option_value_exception_msg();
+   test_invalid_bool_value_exception_msg();
+   test_multiple_values_not_allowed_exception_msg();
+   test_required_option_exception_msg();
+   test_at_least_one_value_required_exception_msg();
+   test_empty_value();
+
+   string test_name;
+   string expected_message;
+
+
+   // check_reading_file
+   test_name        = "check_reading_file";
+   expected_message = "can not read options configuration file 'no_such_file'";
+   test_exception<reading_file>(test_name, expected_message, check_reading_file);
+
+   // config_file_wildcard
+   test_name        = "config_file_wildcard";
+   expected_message = "options 'outpu*' and 'outp*' will both match the same arguments from the configuration file";
+   test_exception<error>(test_name, expected_message, config_file_wildcard);
+
+   // unrecognized_line
+   test_name        = "unrecognized_line";
+   expected_message = "the options configuration file contains an invalid line 'funny wierd line'";
+   test_exception<invalid_syntax>(test_name, expected_message, unrecognized_line);
+
+
+   // abbreviated_options_in_config_file
+   test_name        = "abbreviated_options_in_config_file";
+   expected_message = "abbreviated option names are not permitted in options configuration files";
+   test_exception<error>(test_name, expected_message, abbreviated_options_in_config_file);
+
+   test_name        = "too_many_positional_options";
+   expected_message = "too many positional options have been specified on the command line";
+   test_exception<too_many_positional_options_error>(
+                          test_name, expected_message, too_many_positional_options);
+
+   test_invalid_command_line_style_exception_msg();
+
+
+   return 0;
+}
+

test/minitest.hpp

@@ -0,0 +1,25 @@
+#ifndef BOOST_PROGRAM_OPTIONS_MINITEST
+#define BOOST_PROGRAM_OPTIONS_MINITEST
+
+#include <assert.h>
+#include <iostream>
+#include <stdlib.h>
+
+#define BOOST_REQUIRE(b) assert(b)
+#define BOOST_CHECK(b) assert(b)
+#define BOOST_CHECK_EQUAL(a, b) assert(a == b)
+#define BOOST_ERROR(description) std::cerr << description; std::cerr << "\n"; abort();
+#define BOOST_CHECK_THROW(expression, exception) \
+    try \
+    { \
+        expression; \
+        BOOST_ERROR("expected exception not thrown");\
+        throw 10; \
+    } \
+    catch(exception &) \
+    { \
+    }
+
+
+
+#endif

test/optional_test.cpp

@@ -0,0 +1,53 @@
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#include <boost/program_options.hpp>
+namespace po = boost::program_options;
+
+#include <boost/optional.hpp>
+
+#include <string>
+
+#include "minitest.hpp"
+
+std::vector<std::string> sv(const char* array[], unsigned size)
+{
+    std::vector<std::string> r;
+    for (unsigned i = 0; i < size; ++i)
+        r.push_back(array[i]);
+    return r;
+}
+
+void test_optional()
+{
+    boost::optional<int> foo, bar, baz;
+
+    po::options_description desc;
+    desc.add_options()
+        ("foo,f", po::value(&foo), "")
+        ("bar,b", po::value(&bar), "")
+        ("baz,z", po::value(&baz), "")
+        ;
+
+    const char* cmdline1_[] = { "--foo=12", "--bar", "1"};
+    std::vector<std::string> cmdline1 = sv(cmdline1_,
+                                           sizeof(cmdline1_)/sizeof(const char*));
+    po::variables_map vm;
+    po::store(po::command_line_parser(cmdline1).options(desc).run(), vm);
+    po::notify(vm);
+
+    BOOST_REQUIRE(!!foo);
+    BOOST_CHECK(*foo == 12);
+
+    BOOST_REQUIRE(!!bar);
+    BOOST_CHECK(*bar == 1);
+
+    BOOST_CHECK(!baz);
+}
+
+int main(int, char*[])
+{
+    test_optional();
+    return 0;
+}

test/options_description_test.cpp

@@ -10,89 +10,338 @@ using namespace boost::program_options;
 #include <boost/function.hpp>
 using namespace boost;
 
-#define BOOST_INCLUDE_MAIN  // for testing, include rather than link
-#include <boost/test/test_tools.hpp>
-
 #include <utility>
+#include <string>
+#include <sstream>
 using namespace std;
 
-/*  This is very wierd test case -- it tests trivial things. After writing it,
-    I think that XP folks must be somehow wrong.
-*/
-void test_option_description_construction()
-{
-    option_description d1("a", new untyped_value(), "desc1");
-    BOOST_TEST(d1.long_name() == "a");
-    BOOST_TEST(d1.description() == "desc1");
-    BOOST_TEST(d1.semantic()->name() == "arg");
+#include "minitest.hpp"
 
-    // It is not possible to compare boost::function
-    #if 0
-    function<string, string> f1;
-    BOOST_TEST(&option_description("x", "y", "z").
-               validator(f1).validator() ==
-               &f1);
-    function<void, string> f2;
-    BOOST_TEST(&option_description("x", "y", "z").
-               notify(f2).notify() ==
-               &f2);
-    #endif
-
-    option_description d4("foo,f", new untyped_value(), "desc1");
-    BOOST_CHECK(d4.long_name() == "foo");
-    BOOST_CHECK(d4.short_name() == "f");
-}
-
-void test_options_description()
+void test_type()
 {
     options_description desc;
-
-    shared_ptr<option_description> d1(
-        new option_description("first,f", new untyped_value(), ""));
-    desc.add(d1);
-    BOOST_TEST(desc.count("first") == 1);
-    BOOST_TEST(desc.count("-f") == 1);
-    BOOST_TEST(desc.keys().size() == 2);
-    BOOST_TEST(desc.keys().count("first") == 1);
-    BOOST_TEST(desc.keys().count("-f") == 1);
-
     desc.add_options()
-        ("second,s", new untyped_value())
-        ("third,t", new untyped_value())
+        ("foo", value<int>(), "")
+        ("bar", value<string>(), "")
         ;
-    BOOST_TEST(desc.count("second") == 1);
-    BOOST_TEST(desc.count("-s") == 1);
+    
+#ifndef BOOST_NO_RTTI
+    const typed_value_base* b = dynamic_cast<const typed_value_base*>
+        (desc.find("foo", false).semantic().get());
+    BOOST_CHECK(b);
+    BOOST_CHECK(b->value_type() == typeid(int));
 
-    desc.add_options()
-        (",x", new untyped_value)
-        ;
-    BOOST_TEST(desc.primary_keys().size() == 4);
-    BOOST_TEST(desc.primary_keys().count("first") == 1);
-    BOOST_TEST(desc.primary_keys().count("second") == 1);
-    BOOST_TEST(desc.primary_keys().count("third") == 1);
-    BOOST_TEST(desc.primary_keys().count("-x") == 1);
+    const typed_value_base* b2 = dynamic_cast<const typed_value_base*>
+        (desc.find("bar", false).semantic().get());
+    BOOST_CHECK(b2);
+    BOOST_CHECK(b2->value_type() == typeid(string));
+#endif
 }
 
 void test_approximation()
 {
     options_description desc;
     desc.add_options()
-    ("foo", new untyped_value())
-    ("fee", new untyped_value())
-    ("baz", new untyped_value());
+        ("foo", new untyped_value())
+        ("fee", new untyped_value())
+        ("baz", new untyped_value())
+        ("all-chroots", new untyped_value())
+        ("all-sessions", new untyped_value())
+        ("all", new untyped_value())
+        ;
 
-    BOOST_TEST(desc.count_approx("f") == 2);
-    BOOST_TEST(desc.count_approx("foo") == 1);
-    set<string> a = desc.approximations("f");
-    BOOST_TEST(a.size() == 2);
-    BOOST_TEST(*a.begin() == "fee");
-    BOOST_TEST(*(++a.begin()) == "foo");
+    BOOST_CHECK_EQUAL(desc.find("fo", true).long_name(), "foo");
+
+    BOOST_CHECK_EQUAL(desc.find("all", true).long_name(), "all");
+    BOOST_CHECK_EQUAL(desc.find("all-ch", true).long_name(), "all-chroots");
+
+    options_description desc2;
+    desc2.add_options()
+        ("help", "display this message")
+        ("config", value<string>(), "config file name")
+        ("config-value", value<string>(), "single config value")
+        ;
+
+    BOOST_CHECK_EQUAL(desc2.find("config", true).long_name(), "config");
+    BOOST_CHECK_EQUAL(desc2.find("config-value", true).long_name(), 
+                      "config-value");
+
+
+//    BOOST_CHECK(desc.count_approx("foo") == 1);
+//    set<string> a = desc.approximations("f");
+//    BOOST_CHECK(a.size() == 2);
+//    BOOST_CHECK(*a.begin() == "fee");
+//    BOOST_CHECK(*(++a.begin()) == "foo");
 }
 
-int test_main(int, char* [])
+void test_approximation_with_multiname_options()
 {
-    test_option_description_construction();
-    test_options_description();
+    options_description desc;
+    desc.add_options()
+        ("foo", new untyped_value())
+        ("fee", new untyped_value())
+        ("fe,baz", new untyped_value())
+        ("chroots,all-chroots", new untyped_value())
+        ("sessions,all-sessions", new untyped_value())
+        ("everything,all", new untyped_value())
+        ("qux,fo", new untyped_value())
+        ;
+
+    BOOST_CHECK_EQUAL(desc.find("fo", true).long_name(), "qux");
+
+    BOOST_CHECK_EQUAL(desc.find("all", true).long_name(), "everything");
+    BOOST_CHECK_EQUAL(desc.find("all-ch", true).long_name(), "chroots");
+
+    BOOST_CHECK_EQUAL(desc.find("foo", false, false, false).long_names().second, 1u);
+    BOOST_CHECK_EQUAL(desc.find("foo", false, false, false).long_names().first[0], "foo");
+
+    BOOST_CHECK_EQUAL(desc.find("fe", false, false, false).long_names().second, 2u);
+    BOOST_CHECK_EQUAL(desc.find("fe", false, false, false).long_names().first[0], "fe");
+    BOOST_CHECK_EQUAL(desc.find("baz", false, false, false).long_names().first[1], "baz");
+
+    BOOST_CHECK_EQUAL(desc.find("baz", false, false, false).long_names().second, 2u);
+    BOOST_CHECK_EQUAL(desc.find("baz", false, false, false).long_names().first[0], "fizbaz");
+    BOOST_CHECK_EQUAL(desc.find("baz", false, false, false).long_names().first[1], "baz");
+}
+
+void test_long_names_for_option_description()
+{
+    options_description desc;
+    desc.add_options()
+        ("foo", new untyped_value())
+        ("fe,baz", new untyped_value())
+        ("chroots,all-chroots", new untyped_value())
+        ("sessions,all-sessions", new untyped_value())
+        ("everything,all", new untyped_value())
+        ("qux,fo,q", new untyped_value())
+        ;
+
+    BOOST_CHECK_EQUAL(desc.find("foo", false, false, false).long_names().second, 1u);
+    BOOST_CHECK_EQUAL(desc.find("foo", false, false, false).long_names().first[0], "foo");
+
+    BOOST_CHECK_EQUAL(desc.find("fe", false, false, false).long_names().second, 2u);
+    BOOST_CHECK_EQUAL(desc.find("fe", false, false, false).long_names().first[0], "fe");
+    BOOST_CHECK_EQUAL(desc.find("baz", false, false, false).long_names().first[1], "baz");
+
+    BOOST_CHECK_EQUAL(desc.find("qux", false, false, false).long_names().second, 2u);
+    BOOST_CHECK_EQUAL(desc.find("qux", false, false, false).long_names().first[0], "qux");
+    BOOST_CHECK_EQUAL(desc.find("qux", false, false, false).long_names().first[1], "fo");
+}
+
+
+void test_formatting()
+{
+    // Long option descriptions used to crash on MSVC-8.0.
+    options_description desc;
+    desc.add_options()(
+        "test", new untyped_value(),
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo"
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo"
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo"
+        "foo foo foo foo foo foo foo foo foo foo foo foo foo foo")
+      ("list", new untyped_value(),
+         "a list:\n      \t"
+             "item1, item2, item3, item4, item5, item6, item7, item8, item9, "
+             "item10, item11, item12, item13, item14, item15, item16, item17, item18")
+      ("well_formated", new untyped_value(), 
+                        "As you can see this is a very well formatted option description.\n"
+                        "You can do this for example:\n\n"
+                        "Values:\n"
+                        "  Value1: \tdoes this and that, bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla\n"
+                        "  Value2: \tdoes something else, bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla\n\n"
+                        "    This paragraph has a first line indent only, bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla")
+      ;
+
+    stringstream ss;
+    ss << desc;
+    BOOST_CHECK_EQUAL(ss.str(),
+"  --test arg            foo foo foo foo foo foo foo foo foo foo foo foo foo \n"
+"                        foofoo foo foo foo foo foo foo foo foo foo foo foo foo \n"
+"                        foofoo foo foo foo foo foo foo foo foo foo foo foo foo \n"
+"                        foofoo foo foo foo foo foo foo foo foo foo foo foo foo \n"
+"                        foo\n"
+"  --list arg            a list:\n"
+"                              item1, item2, item3, item4, item5, item6, item7, \n"
+"                              item8, item9, item10, item11, item12, item13, \n"
+"                              item14, item15, item16, item17, item18\n"
+"  --well_formated arg   As you can see this is a very well formatted option \n"
+"                        description.\n"
+"                        You can do this for example:\n"
+"                        \n"
+"                        Values:\n"
+"                          Value1: does this and that, bla bla bla bla bla bla \n"
+"                                  bla bla bla bla bla bla bla bla bla\n"
+"                          Value2: does something else, bla bla bla bla bla bla \n"
+"                                  bla bla bla bla bla bla bla bla bla\n"
+"                        \n"
+"                            This paragraph has a first line indent only, bla \n"
+"                        bla bla bla bla bla bla bla bla bla bla bla bla bla bla\n"
+   );
+}
+
+void test_multiname_option_formatting()
+{
+    options_description desc;
+    desc.add_options()
+      ("foo,bar", new untyped_value(), "a multiple-name option")
+    ;
+
+    stringstream ss;
+    ss << desc;
+    BOOST_CHECK_EQUAL(ss.str(),
+"  --foo arg             a multiple-name option\n"
+   );
+}
+
+
+void test_formatting_description_length()
+{
+    {
+        options_description desc("",
+                                 options_description::m_default_line_length,
+                                 options_description::m_default_line_length / 2U);
+        desc.add_options()
+            ("an-option-that-sets-the-max", new untyped_value(), // > 40 available for desc
+            "this description sits on the same line, but wrapping should still work correctly")
+            ("a-long-option-that-would-leave-very-little-space-for-description", new untyped_value(),
+            "the description of the long opt, but placed on the next line\n"
+            "    \talso ensure that the tabulation works correctly when a"
+            " description size has been set");
+
+        stringstream ss;
+        ss << desc;
+        BOOST_CHECK_EQUAL(ss.str(),
+        "  --an-option-that-sets-the-max arg     this description sits on the same line,\n"
+        "                                        but wrapping should still work \n"
+        "                                        correctly\n"
+        "  --a-long-option-that-would-leave-very-little-space-for-description arg\n"
+        "                                        the description of the long opt, but \n"
+        "                                        placed on the next line\n"
+        "                                            also ensure that the tabulation \n"
+        "                                            works correctly when a description \n"
+        "                                            size has been set\n");
+    }
+    {
+        // the default behaviour reserves 23 (+1 space) characters for the
+        // option column; this shows that the min_description_length does not
+        // breach that.
+        options_description desc("",
+                                 options_description::m_default_line_length,
+                                 options_description::m_default_line_length - 10U); // leaves < 23 (default option space)
+        desc.add_options()
+            ("an-option-that-encroaches-description", new untyped_value(),
+            "this description should always be placed on the next line, and wrapping should continue as normal");
+
+        stringstream ss;
+        ss << desc;
+        BOOST_CHECK_EQUAL(ss.str(),
+        "  --an-option-that-encroaches-description arg\n"
+       //123456789_123456789_
+        "          this description should always be placed on the next line, and \n"
+        "          wrapping should continue as normal\n");
+    }
+}
+
+void test_long_default_value()
+{
+    options_description desc;
+    desc.add_options()
+        ("cfgfile,c",
+         value<string>()->default_value("/usr/local/etc/myprogramXXXXXXXXX/configuration.conf"),
+         "the configfile")
+       ;
+
+    stringstream ss;
+    ss << desc;
+    BOOST_CHECK_EQUAL(ss.str(),
+"  -c [ --cfgfile ] arg (=/usr/local/etc/myprogramXXXXXXXXX/configuration.conf)\n"
+"                                        the configfile\n"
+   );
+}
+
+void test_word_wrapping()
+{
+   options_description desc("Supported options");
+   desc.add_options()
+      ("help",    "this is a sufficiently long text to require word-wrapping")
+      ("prefix", value<string>()->default_value("/h/proj/tmp/dispatch"), "root path of the dispatch installation")
+      ("opt1",    "this_is_a_sufficiently_long_text_to_require_word-wrapping_but_cannot_be_wrapped")
+      ("opt2",    "this_is_a_sufficiently long_text_to_require_word-wrapping")
+      ("opt3",    "this_is_a sufficiently_long_text_to_require_word-wrapping_but_will_not_be_wrapped")
+      ;
+    stringstream ss;
+    ss << desc;    
+    BOOST_CHECK_EQUAL(ss.str(),
+"Supported options:\n"
+"  --help                               this is a sufficiently long text to \n"
+"                                       require word-wrapping\n"
+"  --prefix arg (=/h/proj/tmp/dispatch) root path of the dispatch installation\n"
+"  --opt1                               this_is_a_sufficiently_long_text_to_requ\n"
+"                                       ire_word-wrapping_but_cannot_be_wrapped\n"
+"  --opt2                               this_is_a_sufficiently \n"
+"                                       long_text_to_require_word-wrapping\n"
+"  --opt3                               this_is_a sufficiently_long_text_to_requ\n"
+"                                       ire_word-wrapping_but_will_not_be_wrappe\n"
+"                                       d\n"
+   );
+}
+
+void test_default_values()
+{
+   options_description desc("Supported options");
+   desc.add_options()
+      ("maxlength", value<double>()->default_value(.1, "0.1"), "Maximum edge length to keep.")
+      ;
+   stringstream ss;
+   ss << desc;    
+   BOOST_CHECK_EQUAL(ss.str(),
+"Supported options:\n"
+"  --maxlength arg (=0.1) Maximum edge length to keep.\n"
+   );   
+}
+
+void test_value_name()
+{
+    options_description desc("Supported options");
+    desc.add_options()
+        ("include", value<string>()->value_name("directory"), "Search for headers in 'directory'.")
+        ;
+
+    stringstream ss;
+    ss << desc;
+   BOOST_CHECK_EQUAL(ss.str(),
+"Supported options:\n"
+"  --include directory   Search for headers in 'directory'.\n"
+   );
+}
+
+void test_multiname_key_and_switch_selection()
+{
+    // cases:
+    // foo,f -> f
+    // foo, c -> c
+    // foo,f,g -> g
+    // f,g,h -> h
+    // f,foo throws
+    // foo,bar -> no switch
+    // foo,f,bar -> no switch
+
+    // what about empty strings - consecutive ,'s ?
+}
+
+int main(int, char* [])
+{
+    test_type();
     test_approximation();
+    test_long_names_for_option_description();
+    test_formatting();
+    test_multiname_key_and_switch_selection();
+    test_multiname_option_formatting();
+    test_formatting_description_length();
+    test_long_default_value();
+    test_word_wrapping();
+    test_default_values();
+    test_value_name();
     return 0;
 }
+

test/parsers_test.cpp

@@ -6,6 +6,7 @@
 
 #include <boost/program_options/parsers.hpp>
 #include <boost/program_options/options_description.hpp>
+#include <boost/program_options/variables_map.hpp>
 using namespace boost::program_options;
 // We'll use po::value everywhere to workaround vc6 bug.
 namespace po = boost::program_options;
@@ -13,13 +14,18 @@ namespace po = boost::program_options;
 #include <boost/function.hpp>
 using namespace boost;
 
-#define BOOST_INCLUDE_MAIN  // for testing, include rather than link
-#include <boost/test/test_tools.hpp>
-
 #include <sstream>
+#include <iostream>
+#include <iomanip>
 using namespace std;
 
+#if defined(__sun)
+#include <stdlib.h> // for putenv on solaris
+#else
 #include <cstdlib> // for putenv
+#endif
+
+#include "minitest.hpp"
 
 #define TEST_CHECK_THROW(expression, exception, description) \
     try \
@@ -52,7 +58,7 @@ void check_value(const option& option, const char* name, const char* value)
     BOOST_CHECK(option.value.front() == value);
 }
 
-vector<string> sv(char* array[], unsigned size)
+vector<string> sv(const char* array[], unsigned size)
 {
     vector<string> r;
     for (unsigned i = 0; i < size; ++i)
@@ -60,104 +66,238 @@ vector<string> sv(char* array[], unsigned size)
     return r;
 }
 
-void test_command_line()
+pair<string, string> additional_parser(const std::string&)
 {
-    // The following commented out blocks used to test parsing
-    // command line without syntax specification behaviour.
-    // It is disabled now and probably will never be enabled again:
-    // it is not possible to figure out what command line means without
-    // user's help.
-    #if 0
+    return pair<string, string>();
+}
+
+namespace command_line {
+
+#if 0
+// The following commented out blocks used to test parsing
+// command line without syntax specification behaviour.
+// It is disabled now and probably will never be enabled again:
+// it is not possible to figure out what command line means without
+// user's help.
+void test_parsing_without_specifying_options() {
     char* cmdline1[] = { "--a", "--b=12", "-f", "-g4", "-", "file" };
-
-    options_and_arguments a1 =
-        parse_command_line(cmdline1,
-                           cmdline1 + sizeof(cmdline1)/sizeof(cmdline1[0]));
-
-    BOOST_CRITICAL_TEST(a1.options().size() == 4);
-    BOOST_TEST(a1.options()[0] == msp("a", ""));
-    BOOST_TEST(a1.options()[1] == msp("b", "12"));
-    BOOST_TEST(a1.options()[2] == msp("-f", ""));
-    BOOST_TEST(a1.options()[3] == msp("-g", "4"));
-    BOOST_CRITICAL_TEST(a1.arguments().size() == 2);
-    BOOST_TEST(a1.arguments()[0] == "-");
-    BOOST_TEST(a1.arguments()[1] == "file");
-
+    options_and_arguments a1 = parse_command_line(cmdline1,
+            cmdline1 + sizeof(cmdline1) / sizeof(cmdline1[0]));
+    BOOST_REQUIRE(a1.options().size() == 4);
+    BOOST_CHECK(a1.options()[0] == msp("a", ""));
+    BOOST_CHECK(a1.options()[1] == msp("b", "12"));
+    BOOST_CHECK(a1.options()[2] == msp("-f", ""));
+    BOOST_CHECK(a1.options()[3] == msp("-g", "4"));
+    BOOST_REQUIRE(a1.arguments().size() == 2);
+    BOOST_CHECK(a1.arguments()[0] == "-");
+    BOOST_CHECK(a1.arguments()[1] == "file");
     char* cmdline2[] = { "--a", "--", "file" };
+    options_and_arguments a2 = parse_command_line(cmdline2,
+            cmdline2 + sizeof(cmdline2) / sizeof(cmdline2[0]));
+    BOOST_REQUIRE(a2.options().size() == 1);
+    BOOST_CHECK(a2.options()[0] == msp("a", ""));
+    BOOST_CHECK(a2.arguments().size() == 1);
+    BOOST_CHECK(a2.arguments()[0] == "file");
+}
+#endif
 
-    options_and_arguments a2 =
-        parse_command_line(cmdline2,
-                           cmdline2 + sizeof(cmdline2)/sizeof(cmdline2[0]));
-
-    BOOST_CRITICAL_TEST(a2.options().size() == 1);
-    BOOST_TEST(a2.options()[0] == msp("a", ""));
-    BOOST_TEST(a2.arguments().size() == 1);
-    BOOST_TEST(a2.arguments()[0] == "file");
-    #endif
-    
+void test_many_different_options() {
     options_description desc;
     desc.add_options()
         ("foo,f", new untyped_value(), "")
-        // Explicit qualification is a workaround for vc6
-        ("bar,b", po::value<std::string>()->implicit(), "")
+        ( // Explicit qualification is a workaround for vc6
+            "bar,b", po::value<std::string>(), "")
+        ("car,voiture", new untyped_value())
+        ("dog,dawg", new untyped_value())
         ("baz", new untyped_value())
-        ("plug*", new untyped_value())
-        ;
-    char* cmdline3_[] = { "--foo=12", "-f4", "--bar=11", "--bar", "-b4", "-b",
-                         "--plug3=10"};
+        ("plug*", new untyped_value());
+    const char* cmdline3_[] = { "--foo=12", "-f4", "--bar=11", "-b4",
+            "--voiture=15", "--dawg=16", "--dog=17", "--plug3=10" };
     vector<string> cmdline3 = sv(cmdline3_,
-                                 sizeof(cmdline3_)/sizeof(cmdline3_[0]));
-    vector<option> a3 = 
-        command_line_parser(cmdline3).options(desc).run().options;
-                       
-    BOOST_CRITICAL_TEST(a3.size() == 7);
-
+            sizeof(cmdline3_) / sizeof(const char*));
+    vector<option> a3 =
+            command_line_parser(cmdline3).options(desc).run().options;
+    BOOST_CHECK_EQUAL(a3.size(), 8u);
     check_value(a3[0], "foo", "12");
     check_value(a3[1], "foo", "4");
     check_value(a3[2], "bar", "11");
+    check_value(a3[3], "bar", "4");
+    check_value(a3[4], "car", "15");
+    check_value(a3[5], "dog", "16");
+    check_value(a3[6], "dog", "17");
+    check_value(a3[7], "plug3", "10");
 
-    BOOST_TEST(a3[3].string_key == "bar");
-    BOOST_CRITICAL_TEST(a3[3].value.size() == 0);
-
-    check_value(a3[4], "bar", "4");
-
-    BOOST_TEST(a3[5].string_key == "bar");
-    BOOST_CRITICAL_TEST(a3[5].value.size() == 0);
-
-    check_value(a3[6], "plug3", "10");
+    // Regression test: check that '0' as style is interpreted as 
+    // 'default_style'
+    vector<option> a4 = parse_command_line(
+            sizeof(cmdline3_) / sizeof(const char*), cmdline3_, desc, 0,
+            additional_parser).options;
+    // The default style is unix-style, where the first argument on the command-line
+    // is the name of a binary, not an option value, so that should be ignored
+    BOOST_CHECK_EQUAL(a4.size(), 7u);
+    check_value(a4[0], "foo", "4");
+    check_value(a4[1], "bar", "11");
+    check_value(a4[2], "bar", "4");
+    check_value(a4[3], "car", "15");
+    check_value(a4[4], "dog", "16");
+    check_value(a4[5], "dog", "17");
+    check_value(a4[6], "plug3", "10");
 }
 
-void test_config_file()
+void test_not_crashing_with_empty_string_values() {
+    // Check that we don't crash on empty values of type 'string'
+    const char* cmdline4[] = { "", "--open", "" };
+    options_description desc2;
+    desc2.add_options()("open", po::value<string>());
+    variables_map vm;
+    po::store(
+            po::parse_command_line(sizeof(cmdline4) / sizeof(const char*),
+                    const_cast<char**>(cmdline4), desc2), vm);
+}
+
+void test_multitoken() {
+    const char* cmdline5[] = { "", "-p7", "-o", "1", "2", "3", "-x8" };
+    options_description desc3;
+    desc3.add_options()
+        (",p", po::value<string>())
+        (",o", po::value<string>()->multitoken())
+        (",x", po::value<string>());
+    vector<option> a5 = parse_command_line(
+            sizeof(cmdline5) / sizeof(const char*),
+            const_cast<char**>(cmdline5), desc3, 0, additional_parser).options;
+    BOOST_CHECK_EQUAL(a5.size(), 3u);
+    check_value(a5[0], "-p", "7");
+    BOOST_REQUIRE(a5[1].value.size() == 3);
+    BOOST_CHECK_EQUAL(a5[1].string_key, "-o");
+    BOOST_CHECK_EQUAL(a5[1].value[0], "1");
+    BOOST_CHECK_EQUAL(a5[1].value[1], "2");
+    BOOST_CHECK_EQUAL(a5[1].value[2], "3");
+    check_value(a5[2], "-x", "8");
+}
+
+void test_multitoken_and_multiname() {
+    const char* cmdline[] = { "program", "-fone", "-b", "two", "--foo", "three", "four", "-zfive", "--fee", "six" };
+    options_description desc;
+    desc.add_options()
+        ("bar,b", po::value<string>())
+        ("foo,fee,f", po::value<string>()->multitoken())
+        ("fizbaz,baz,z", po::value<string>());
+
+    vector<option> parsed_options = parse_command_line(
+            sizeof(cmdline) / sizeof(const char*),
+            const_cast<char**>(cmdline), desc, 0, additional_parser).options;
+
+    BOOST_CHECK_EQUAL(parsed_options.size(), 5u);
+    check_value(parsed_options[0], "foo", "one");
+    check_value(parsed_options[1], "bar", "two");
+    BOOST_CHECK_EQUAL(parsed_options[2].string_key, "foo");
+    BOOST_REQUIRE(parsed_options[2].value.size() == 2);
+    BOOST_CHECK_EQUAL(parsed_options[2].value[0], "three");
+    BOOST_CHECK_EQUAL(parsed_options[2].value[1], "four");
+    check_value(parsed_options[3], "fizbaz", "five");
+    check_value(parsed_options[4], "foo", "six");
+
+    const char* cmdline_2[] = { "program", "-fone", "-b", "two", "--fee", "three", "four", "-zfive", "--foo", "six" };
+
+    parsed_options = parse_command_line(
+            sizeof(cmdline_2) / sizeof(const char*),
+            const_cast<char**>(cmdline_2), desc, 0, additional_parser).options;
+
+    BOOST_CHECK_EQUAL(parsed_options.size(), 5u);
+    check_value(parsed_options[0], "foo", "one");
+    check_value(parsed_options[1], "bar", "two");
+    BOOST_CHECK_EQUAL(parsed_options[2].string_key, "foo");
+    BOOST_REQUIRE(parsed_options[2].value.size() == 2);
+    BOOST_CHECK_EQUAL(parsed_options[2].value[0], "three");
+    BOOST_CHECK_EQUAL(parsed_options[2].value[1], "four");
+    check_value(parsed_options[3], "fizbaz", "five");
+    check_value(parsed_options[4], "foo", "six");
+}
+
+
+void test_multitoken_vector_option() {
+    po::options_description desc4("");
+    desc4.add_options()
+        ("multitoken,multi-token,m", po::value<std::vector<std::string> >()->multitoken(), "values")
+        ("file", po::value<std::string>(), "the file to process");
+    po::positional_options_description p;
+    p.add("file", 1);
+    const char* cmdline6[] = { "", "-m", "token1", "token2", "--", "some_file" };
+    vector<option> a6 =
+            command_line_parser(sizeof(cmdline6) / sizeof(const char*),
+                    const_cast<char**>(cmdline6)).options(desc4).positional(p).run().options;
+    BOOST_CHECK_EQUAL(a6.size(), 2u);
+    BOOST_REQUIRE(a6[0].value.size() == 2);
+    BOOST_CHECK_EQUAL(a6[0].string_key, "multitoken");
+    BOOST_CHECK_EQUAL(a6[0].value[0], "token1");
+    BOOST_CHECK_EQUAL(a6[0].value[1], "token2");
+    BOOST_CHECK_EQUAL(a6[1].string_key, "file");
+    BOOST_REQUIRE(a6[1].value.size() == 1);
+    BOOST_CHECK_EQUAL(a6[1].value[0], "some_file");
+}
+
+} // namespace command_line
+
+void test_command_line()
+{
+    #if 0
+    command_line::test_parsing_without_specifying_options();
+    #endif
+    command_line::test_many_different_options();
+    // Check that we don't crash on empty values of type 'string'
+    command_line::test_not_crashing_with_empty_string_values();
+    command_line::test_multitoken();
+    command_line::test_multitoken_vector_option();
+    command_line::test_multitoken_and_multiname();
+}
+
+void test_config_file(const char* config_file)
 {
     options_description desc;
     desc.add_options()
         ("gv1", new untyped_value)
         ("gv2", new untyped_value)
+        ("empty_value", new untyped_value)
         ("plug*", new untyped_value)
         ("m1.v1", new untyped_value)
         ("m1.v2", new untyped_value)
+        ("m1.v3,alias3", new untyped_value)
         ("b", bool_switch())
     ;
 
     const char content1[] =
     " gv1 = 0#asd\n"
+    "empty_value = \n"
     "plug3 = 7\n"
     "b = true\n"
     "[m1]\n"
     "v1 = 1\n"
     "\n"
     "v2 = 2\n"    
+    "v3 = 3\n"
     ;
 
     stringstream ss(content1);
     vector<option> a1 = parse_config_file(ss, desc).options;
-    BOOST_CRITICAL_TEST(a1.size() == 5);
+    BOOST_REQUIRE(a1.size() == 7);
     check_value(a1[0], "gv1", "0");
-    check_value(a1[1], "plug3", "7");
-    check_value(a1[2], "b", "true");
-    check_value(a1[3], "m1.v1", "1");
-    check_value(a1[4], "m1.v2", "2");
-
+    check_value(a1[1], "empty_value", "");
+    check_value(a1[2], "plug3", "7");
+    check_value(a1[3], "b", "true");
+    check_value(a1[4], "m1.v1", "1");
+    check_value(a1[5], "m1.v2", "2");
+    check_value(a1[6], "m1.v3", "3");
+    
+    // same test, but now options come from file 
+    vector<option> a2 = parse_config_file<char>(config_file, desc).options;
+    BOOST_REQUIRE(a2.size() == 7);
+    check_value(a2[0], "gv1", "0");
+    check_value(a2[1], "empty_value", "");
+    check_value(a2[2], "plug3", "7");
+    check_value(a2[3], "b", "true");
+    check_value(a2[4], "m1.v1", "1");
+    check_value(a2[5], "m1.v2", "2");
+    check_value(a2[6], "m1.v3", "3");
 }
 
 void test_environment()
@@ -168,27 +308,81 @@ void test_environment()
         ("bar", new untyped_value, "")
         ;
 
-#if defined(_WIN32) && ! defined(__BORLANDC__)
+#if (defined(_WIN32) && ! defined(BOOST_BORLANDC) && ! defined(BOOST_EMBTC)) || (defined(__CYGWIN__))
     _putenv("PO_TEST_FOO=1");
 #else
-    putenv("PO_TEST_FOO=1");
+    putenv(const_cast<char*>("PO_TEST_FOO=1"));
 #endif
     parsed_options p = parse_environment(desc, "PO_TEST_");
 
     BOOST_REQUIRE(p.options.size() == 1);
-    BOOST_CHECK(p.options[0].string_key == "foo");
+    BOOST_CHECK  (p.options[0].string_key == "foo");
     BOOST_REQUIRE(p.options[0].value.size() == 1);
-    BOOST_CHECK(p.options[0].value[0] == "1");
+    BOOST_CHECK  (p.options[0].value[0] == "1");
 
     //TODO: since 'bar' does not allow a value, it cannot appear in environemt,
     // which already has a value.
 }
 
-int test_main(int, char* [])
+void test_unregistered()
+{
+    options_description desc;
+
+    const char* cmdline1_[] = { "--foo=12", "--bar", "1"};
+    vector<string> cmdline1 = sv(cmdline1_,
+                                 sizeof(cmdline1_)/sizeof(const char*));
+    vector<option> a1 = 
+        command_line_parser(cmdline1).options(desc).allow_unregistered().run()
+        .options;
+
+    BOOST_REQUIRE(a1.size() == 3);
+    BOOST_CHECK(a1[0].string_key == "foo");
+    BOOST_CHECK(a1[0].unregistered == true);
+    BOOST_REQUIRE(a1[0].value.size() == 1);
+    BOOST_CHECK(a1[0].value[0] == "12");
+    BOOST_CHECK(a1[1].string_key == "bar");
+    BOOST_CHECK(a1[1].unregistered == true);
+    BOOST_CHECK(a1[2].string_key == "");
+    BOOST_CHECK(a1[2].unregistered == false);
+    
+
+    vector<string> a2 = collect_unrecognized(a1, include_positional);
+    BOOST_CHECK(a2[0] == "--foo=12");
+    BOOST_CHECK(a2[1] == "--bar");
+    BOOST_CHECK(a2[2] == "1");
+
+    // Test that storing unregisted options has no effect
+    variables_map vm;
+    
+    store(command_line_parser(cmdline1).options(desc).
+          allow_unregistered().run(),
+          vm);
+
+    BOOST_CHECK_EQUAL(vm.size(), 0u);   
+
+
+    const char content1[] =
+    "gv1 = 0\n"
+    "[m1]\n"
+    "v1 = 1\n"
+    ;
+
+    stringstream ss(content1);
+    vector<option> a3 = parse_config_file(ss, desc, true).options;
+    BOOST_REQUIRE(a3.size() == 2);
+    cout << "XXX" << a3[0].value.front() << "\n";
+    check_value(a3[0], "gv1", "0");
+    check_value(a3[1], "m1.v1", "1");
+}
+
+
+
+int main(int, char* av[])
 {
     test_command_line();
-    test_config_file();
+    test_config_file(av[1]);
     test_environment();
+    test_unregistered();
     return 0;
 }
 

test/positional_options_test.cpp

@@ -12,7 +12,8 @@ namespace po = boost::program_options;
 
 
 #include <boost/limits.hpp>
-#include <boost/test/test_tools.hpp>
+
+#include "minitest.hpp"
 
 #include <vector>
 using namespace std;
@@ -34,7 +35,7 @@ void test_positional_options()
 
     p.add("third", -1);
 
-    BOOST_CHECK_EQUAL(p.max_total_count(), std::numeric_limits<unsigned>::max());
+    BOOST_CHECK_EQUAL(p.max_total_count(), (std::numeric_limits<unsigned>::max)());
     BOOST_CHECK_EQUAL(p.name_for_position(0), "first");
     BOOST_CHECK_EQUAL(p.name_for_position(1), "second");
     BOOST_CHECK_EQUAL(p.name_for_position(2), "second");
@@ -49,28 +50,31 @@ void test_parsing()
         ("first", po::value<int>())
         ("second", po::value<int>())
         ("input-file", po::value< vector<string> >())
+        ("some-other", po::value<string>())
     ;
 
     positional_options_description p;
-    p.add("input-file", 2);
+    p.add("input-file", 2).add("some-other", 1);
 
     vector<string> args;
     args.push_back("--first=10");
     args.push_back("file1");
     args.push_back("--second=10");
     args.push_back("file2");
+    args.push_back("file3");
 
     // Check that positional options are handled.
     parsed_options parsed = 
         command_line_parser(args).options(desc).positional(p).run();
 
-    BOOST_REQUIRE(parsed.options.size() == 4);
+    BOOST_REQUIRE(parsed.options.size() == 5);
     BOOST_CHECK_EQUAL(parsed.options[1].string_key, "input-file");
     BOOST_CHECK_EQUAL(parsed.options[1].value[0], "file1");
     BOOST_CHECK_EQUAL(parsed.options[3].string_key, "input-file");
     BOOST_CHECK_EQUAL(parsed.options[3].value[0], "file2");
+    BOOST_CHECK_EQUAL(parsed.options[4].value[0], "file3");
 
-    args.push_back("file3");
+    args.push_back("file4");
 
     // Check that excessive number of positional options is detected.
     BOOST_CHECK_THROW(command_line_parser(args).options(desc).positional(p)
@@ -78,7 +82,7 @@ void test_parsing()
                       too_many_positional_options_error);
 }
 
-int test_main(int, char* [])
+int main(int, char* [])
 {
     test_positional_options();
     test_parsing();

test/program_options_size_test.py

@@ -21,7 +21,7 @@ void do_it()
       f.write("(\"opt%d\", value<int>())\n")
    f.write(";\n}\n")   
    f.close()
-   os.system(compiler_command + " -c -save-temps -I /home/ghost/Work/boost-rc program_options_test.cpp")
+   os.system(compiler_command + " -c -save-temps -I /home/ghost/Work/Boost/boost-svn program_options_test.cpp")
 
    nm = os.popen("nm -S program_options_test.o")
    for l in nm:
@@ -45,7 +45,7 @@ def run_tests(range, compiler_command):
    print "Avarage: ", (last_size-first_size)/(range[-1]-range[0])
 
 if __name__ == '__main__':
-   for compiler in [ "g++-3.3 -Os", "g++-3.3 -O3", "g++-3.4 -Os", "g++-3.4 -O3"]:
+   for compiler in [ "g++ -Os", "g++ -O3"]:
       print "****", compiler, "****"
       run_tests(range(1, 20), compiler)
 

test/quick.cpp

@@ -0,0 +1,49 @@
+
+// Copyright 2017 Peter Dimov.
+//
+// Distributed under the Boost Software License, Version 1.0.
+//
+// See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt
+
+// See library home page at http://www.boost.org/libs/program_options
+
+#include <boost/program_options.hpp>
+#include <boost/core/lightweight_test.hpp>
+
+namespace po = boost::program_options;
+
+int main( int argc, char const* argv[] )
+{
+    po::options_description desc( "Allowed options" );
+
+    desc.add_options()
+        ( "path,p", po::value<std::string>(), "set initial path" )
+    ;
+
+    po::variables_map vm;
+
+    try
+    {
+        po::store( po::parse_command_line( argc, argv, desc ), vm );
+        po::notify( vm );
+    }
+    catch( std::exception const & x )
+    {
+        std::cerr << "Error: " << x.what() << std::endl;
+        return 1;
+    }
+
+    std::string p;
+
+    if( vm.count( "path" ) )
+    {
+        p = vm[ "path" ].as<std::string>();
+    }
+
+    std::string expected( "initial" );
+
+    BOOST_TEST_EQ( p, expected );
+
+    return boost::report_errors();
+}

test/required_test.cfg

@@ -0,0 +1 @@
+cfgfile = file.cfg

test/required_test.cpp

@@ -0,0 +1,125 @@
+// Copyright Sascha Ochsenknecht 2009.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+#include <boost/program_options.hpp>
+using namespace boost::program_options;
+
+#include <string>
+#include <iostream>
+#include <fstream>
+using namespace std;
+
+#include "minitest.hpp"
+
+
+void required_throw_test()
+{
+   options_description          opts;
+   opts.add_options()
+     ("cfgfile,c", value<string>()->required(), "the configfile")
+     ("fritz,f",   value<string>()->required(), "the output file")
+   ;
+
+   variables_map vm;
+   bool thrown = false;
+   {
+      // This test must throw exception
+      string cmdline = "prg -f file.txt";
+      vector< string > tokens =  split_unix(cmdline);
+      thrown = false;
+      try {
+         store(command_line_parser(tokens).options(opts).run(), vm);
+         notify(vm);    
+      } 
+      catch (required_option& e) {
+         BOOST_CHECK_EQUAL(e.what(), string("the option '--cfgfile' is required but missing"));
+         thrown = true;
+      }      
+      BOOST_CHECK(thrown);
+   }
+   
+   {
+      // This test mustn't throw exception
+      string cmdline = "prg -c config.txt";
+      vector< string > tokens =  split_unix(cmdline);
+      thrown = false;
+      try {
+         store(command_line_parser(tokens).options(opts).run(), vm);
+         notify(vm);    
+      } 
+      catch (required_option& e) {
+         thrown = true;
+      }
+      BOOST_CHECK(!thrown);
+   }
+}
+
+
+
+void simple_required_test(const char* config_file)
+{
+   options_description          opts;
+   opts.add_options()
+     ("cfgfile,c", value<string>()->required(), "the configfile")
+     ("fritz,f",   value<string>()->required(), "the output file")
+   ;
+
+   variables_map vm;
+   bool thrown = false;
+   {
+      // This test must throw exception
+      string cmdline = "prg -f file.txt";
+      vector< string > tokens =  split_unix(cmdline);
+      thrown = false;
+      try {
+         // options coming from different sources
+         store(command_line_parser(tokens).options(opts).run(), vm);
+         store(parse_config_file<char>(config_file, opts), vm);
+         notify(vm);    
+      } 
+      catch (required_option& e) {
+         thrown = true;
+      }      
+      BOOST_CHECK(!thrown);
+   }
+}
+
+void multiname_required_test()
+{
+   options_description          opts;
+   opts.add_options()
+     ("foo,bar", value<string>()->required(), "the foo")
+   ;
+
+   variables_map vm;
+   bool thrown = false;
+   {
+      // This test must throw exception
+      string cmdline = "prg --bar file.txt";
+      vector< string > tokens =  split_unix(cmdline);
+      thrown = false;
+      try {
+         // options coming from different sources
+         store(command_line_parser(tokens).options(opts).run(), vm);
+         notify(vm);
+      }
+      catch (required_option& e) {
+         thrown = true;
+      }
+      BOOST_CHECK(!thrown);
+   }
+}
+
+
+
+int main(int /*argc*/, char* av[])
+{  
+   required_throw_test();
+   simple_required_test(av[1]);
+   multiname_required_test();
+   
+   return 0;
+}
+

test/split_test.cpp

@@ -0,0 +1,189 @@
+// Copyright Sascha Ochsenknecht 2009.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+
+#include <boost/program_options/parsers.hpp>
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/variables_map.hpp>
+#include <boost/program_options/cmdline.hpp>
+using namespace boost::program_options;
+
+#include <iostream>
+#include <sstream>
+#include <vector>
+#include <cassert>
+using namespace std;
+
+#include "minitest.hpp"
+
+void check_value(const string& option, const string& value)
+{
+    BOOST_CHECK(option == value);
+}
+
+void split_whitespace(const options_description& description)
+{
+
+   const char* cmdline = "prg --input input.txt \r --optimization 4  \t  --opt \n  option";
+   
+   vector< string > tokens =  split_unix(cmdline, " \t\n\r");
+   
+   BOOST_REQUIRE(tokens.size() == 7);
+   
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "input.txt");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "option");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+void split_equalsign(const options_description& description)
+{
+
+   const char* cmdline = "prg --input=input.txt  --optimization=4 --opt=option";
+   
+   vector< string > tokens =  split_unix(cmdline, "= ");
+ 
+   BOOST_REQUIRE(tokens.size() == 7);
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "input.txt");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "option");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+void split_semi(const options_description& description)
+{
+
+   const char* cmdline = "prg;--input input.txt;--optimization 4;--opt option";
+   
+   vector< string > tokens =  split_unix(cmdline, "; ");
+   
+   BOOST_REQUIRE(tokens.size() == 7);
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "input.txt");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "option");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+void split_quotes(const options_description& description)
+{
+   const char* cmdline = "prg --input \"input.txt input.txt\" --optimization 4 --opt \"option1 option2\"";
+   
+   vector< string > tokens =  split_unix(cmdline, " ");
+ 
+   BOOST_REQUIRE(tokens.size() == 7);
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "input.txt input.txt");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "option1 option2");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+void split_escape(const options_description& description)
+{
+   const char* cmdline = "prg --input \\\"input.txt\\\" --optimization 4 --opt \\\"option1\\ option2\\\"";
+   
+   vector< string > tokens =  split_unix(cmdline, " ");
+  
+   BOOST_REQUIRE(tokens.size() == 7);
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "\"input.txt\"");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "\"option1 option2\"");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+
+void split_single_quote(const options_description& description)
+{
+   const char* cmdline = "prg --input 'input.txt input.txt' --optimization 4 --opt 'option1 option2'";
+   
+   vector< string > tokens =  split_unix(cmdline, " ", "'");
+ 
+   BOOST_REQUIRE(tokens.size() == 7);
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "input.txt input.txt");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "option1 option2");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+void split_defaults(const options_description& description)
+{
+   const char* cmdline = "prg --input \t \'input file.txt\' \t   --optimization 4 --opt \\\"option1\\ option2\\\"";
+   
+   vector< string > tokens =  split_unix(cmdline);
+  
+   BOOST_REQUIRE(tokens.size() == 7);
+   check_value(tokens[0], "prg");
+   check_value(tokens[1], "--input");
+   check_value(tokens[2], "input file.txt");
+   check_value(tokens[3], "--optimization");
+   check_value(tokens[4], "4");
+   check_value(tokens[5], "--opt");
+   check_value(tokens[6], "\"option1 option2\"");
+
+   variables_map vm;  
+   store(command_line_parser(tokens).options(description).run(), vm);
+   notify(vm);
+}
+
+int main(int /*ac*/, char** /*av*/)
+{
+   options_description desc;
+   desc.add_options()
+        ("input,i", value<string>(), "the input file")
+        ("optimization,O", value<unsigned>(), "optimization level")
+        ("opt,o", value<string>(), "misc option")
+      ;
+
+   split_whitespace(desc);
+   split_equalsign(desc);
+   split_semi(desc);
+   split_quotes(desc);
+   split_escape(desc);
+   split_single_quote(desc);
+   split_defaults(desc);
+   
+   return 0;
+}

test/test_convert.cpp

@@ -3,11 +3,12 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
+#include <cstring>
+#include <cassert>
 #include <string>
 #include <fstream>
 #include <sstream>
 #include <iostream>
-#include <cassert>
 #include <boost/progress.hpp>
 #include <boost/bind.hpp>
 #include <boost/ref.hpp>
@@ -15,6 +16,8 @@
 #include <boost/program_options/detail/convert.hpp>
 #include <boost/program_options/detail/utf8_codecvt_facet.hpp>
 
+#include "minitest.hpp"
+
 using namespace std;
 
 string file_content(const string& filename)
@@ -36,8 +39,8 @@ std::wstring from_8_bit_2(const std::string& s,
     std::wstring result;
 
 
-    std::mbstate_t state = {0};
-
+    std::mbstate_t state = std::mbstate_t();
+    
     const char* from = s.data();
     const char* from_end = s.data() + s.size();
     // The interace of cvt is not really iterator-like, and it's
@@ -75,7 +78,7 @@ std::wstring from_8_bit_2(const std::string& s,
 void test_convert(const std::string& input, 
                   const std::string& expected_output)
 {
-    boost::program_options::detail::utf8_codecvt_facet<wchar_t, char> facet;
+    boost::program_options::detail::utf8_codecvt_facet facet;
     
     std::wstring output;
     { 
@@ -94,7 +97,7 @@ void test_convert(const std::string& input,
                 facet);
     }
 
-    assert(output.size()*2 == expected_output.size());
+    BOOST_CHECK(output.size()*2 == expected_output.size());
 
     for(unsigned i = 0; i < output.size(); ++i) {
 
@@ -103,23 +106,23 @@ void test_convert(const std::string& input,
             low &= 0xFF;
             unsigned low2 = expected_output[2*i];
             low2 &= 0xFF;
-            assert(low == low2);
+            BOOST_CHECK(low == low2);
         }
         {        
             unsigned high = output[i];
             high >>= 8;
             high &= 0xFF;
             unsigned high2 = expected_output[2*i+1];            
-            assert(high == high2);
+            BOOST_CHECK(high == high2);
         }
     }
 
     string ref = boost::to_8_bit(output, facet);
 
-    assert(ref == input);
+    BOOST_CHECK(ref == input);
 }
 
-int test_main(int ac, char* av[])
+int main(int ac, char* av[])
 {       
     std::string input = file_content("utf8.txt");
     std::string expected = file_content("ucs2.txt");

test/unicode_test.cpp

@@ -15,12 +15,11 @@ namespace po = boost::program_options;
 #include <boost/function.hpp>
 using namespace boost;
 
-#define BOOST_INCLUDE_MAIN  // for testing, include rather than link
-#include <boost/test/test_tools.hpp>
-
 #include <sstream>
 using namespace std;
 
+#include "minitest.hpp"
+
 // Test that unicode input is forwarded to unicode option without
 // problems.
 void test_unicode_to_unicode()
@@ -35,9 +34,13 @@ void test_unicode_to_unicode()
     args.push_back(L"--foo=\x044F");
 
     variables_map vm;
-    store(wcommand_line_parser(args).options(desc).run(), vm);
+    basic_parsed_options<wchar_t> parsed = 
+        wcommand_line_parser(args).options(desc).run();
+    store(parsed, vm);
 
-    BOOST_CHECK(vm["foo"].as<wstring>() == L"\x044F");           
+    BOOST_CHECK(vm["foo"].as<wstring>() == L"\x044F");
+    BOOST_CHECK(parsed.options[0].original_tokens.size() == 1);
+    BOOST_CHECK(parsed.options[0].original_tokens[0] == L"--foo=\x044F");
 }
 
 // Test that unicode input is property converted into
@@ -46,7 +49,7 @@ void test_unicode_to_unicode()
 void test_unicode_to_native()
 {
     std::codecvt<wchar_t, char, mbstate_t>* facet = 
-        new boost::program_options::detail::utf8_codecvt_facet<wchar_t, char>;
+        new boost::program_options::detail::utf8_codecvt_facet;
     locale::global(locale(locale(), facet));
 
     options_description desc;
@@ -61,13 +64,13 @@ void test_unicode_to_native()
     variables_map vm;
     store(wcommand_line_parser(args).options(desc).run(), vm);
 
-    BOOST_TEST(vm["foo"].as<string>() == "\xD1\x8F");    
+    BOOST_CHECK(vm["foo"].as<string>() == "\xD1\x8F");    
 }
 
 void test_native_to_unicode()
 {
     std::codecvt<wchar_t, char, mbstate_t>* facet = 
-        new boost::program_options::detail::utf8_codecvt_facet<wchar_t, char>;
+        new boost::program_options::detail::utf8_codecvt_facet;
     locale::global(locale(locale(), facet));
 
     options_description desc;
@@ -82,11 +85,10 @@ void test_native_to_unicode()
     variables_map vm;
     store(command_line_parser(args).options(desc).run(), vm);
 
-    BOOST_TEST(vm["foo"].as<wstring>() == L"\x044F");    
+    BOOST_CHECK(vm["foo"].as<wstring>() == L"\x044F");    
 }
 
-
-vector<wstring> sv(wchar_t* array[], unsigned size)
+vector<wstring> sv(const wchar_t* array[], unsigned size)
 {
     vector<wstring> r;
     for (unsigned i = 0; i < size; ++i)
@@ -107,23 +109,24 @@ void test_command_line()
     desc.add_options()
         ("foo,f", new untyped_value(), "")
         // Explicit qualification is a workaround for vc6
-        ("bar,b", po::value<std::string>()->implicit(), "")
+        ("bar,b", po::value<std::string>(), "")
         ("baz", new untyped_value())
-        ("plug*", new untyped_value())
+        ("qux,plug*", new untyped_value())
         ;
 
-    wchar_t* cmdline4_[] = { L"--foo=1\u0FF52", L"-f4", L"--bar=11", L"--bar", 
-                             L"-b4", L"-b", L"--plug3=10"};
+    const wchar_t* cmdline4_[] = { L"--foo=1\u0FF52", L"-f4", L"--bar=11",
+                             L"-b4", L"--plug3=10"};
     vector<wstring> cmdline4 = sv(cmdline4_,
                                   sizeof(cmdline4_)/sizeof(cmdline4_[0]));
     vector<woption> a4 = 
         wcommand_line_parser(cmdline4).options(desc).run().options;
 
-    BOOST_CRITICAL_TEST(a4.size() == 7);
+    BOOST_REQUIRE(a4.size() == 5);
 
     check_value(a4[0], "foo", L"1\u0FF52");
     check_value(a4[1], "foo", L"4");
     check_value(a4[2], "bar", L"11");
+    check_value(a4[4], "qux", L"10");
 }
 
 // Since we've already tested conversion between parser encoding and
@@ -132,7 +135,7 @@ void test_command_line()
 void test_config_file()
 {
     std::codecvt<wchar_t, char, mbstate_t>* facet = 
-        new boost::program_options::detail::utf8_codecvt_facet<wchar_t, char>;
+        new boost::program_options::detail::utf8_codecvt_facet;
     locale::global(locale(locale(), facet));
 
     options_description desc;
@@ -146,10 +149,10 @@ void test_config_file()
     variables_map vm;
     store(parse_config_file(stream, desc), vm);
 
-    BOOST_TEST(vm["foo"].as<string>() == "\xD1\x8F");    
+    BOOST_CHECK(vm["foo"].as<string>() == "\xD1\x8F");    
 }
 
-int test_main(int, char* [])
+int main(int, char* [])
 {
     test_unicode_to_unicode();
     test_unicode_to_native();

test/unrecognized_test.cpp

@@ -0,0 +1,88 @@
+// Copyright Sascha Ochsenknecht 2009.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt
+// or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+
+#include <boost/program_options/cmdline.hpp>
+#include <boost/program_options/options_description.hpp>
+#include <boost/program_options/parsers.hpp>
+#include <boost/program_options/detail/cmdline.hpp>
+using namespace boost::program_options;
+using boost::program_options::detail::cmdline;
+
+#include <iostream>
+#include <sstream>
+#include <vector>
+#include <cassert>
+using namespace std;
+
+#include "minitest.hpp"
+
+
+// Test free function collect_unrecognized()
+//
+//  it collects the tokens of all not registered options. It can be used
+//  to pass them to an own parser implementation
+
+
+
+void test_unrecognize_cmdline() 
+{
+   options_description desc;
+   
+   string content = "prg --input input.txt --optimization 4 --opt option";   
+   vector< string > tokens =  split_unix(content);
+
+   cmdline cmd(tokens);
+   cmd.set_options_description(desc);
+   cmd.allow_unregistered();
+
+   vector< option > opts = cmd.run();
+   vector< string > result = collect_unrecognized(opts, include_positional);
+   
+   BOOST_CHECK_EQUAL(result.size(), 7);
+   BOOST_CHECK_EQUAL(result[0], "prg");
+   BOOST_CHECK_EQUAL(result[1], "--input");
+   BOOST_CHECK_EQUAL(result[2], "input.txt");
+   BOOST_CHECK_EQUAL(result[3], "--optimization");
+   BOOST_CHECK_EQUAL(result[4], "4");
+   BOOST_CHECK_EQUAL(result[5], "--opt");
+   BOOST_CHECK_EQUAL(result[6], "option");
+}
+
+
+
+void test_unrecognize_config() 
+{
+
+   options_description desc;
+   
+   string content  =
+    " input = input.txt\n"
+    " optimization = 4\n"
+    " opt = option\n"
+    ;
+
+   stringstream ss(content);
+   vector< option > opts = parse_config_file(ss, desc, true).options;
+   vector< string > result = collect_unrecognized(opts, include_positional);
+   
+   BOOST_CHECK_EQUAL(result.size(), 6);
+   BOOST_CHECK_EQUAL(result[0], "input");
+   BOOST_CHECK_EQUAL(result[1], "input.txt");
+   BOOST_CHECK_EQUAL(result[2], "optimization");
+   BOOST_CHECK_EQUAL(result[3], "4");
+   BOOST_CHECK_EQUAL(result[4], "opt");
+   BOOST_CHECK_EQUAL(result[5], "option");
+}
+
+
+
+int main(int /*ac*/, char** /*av*/)
+{
+   test_unrecognize_cmdline();
+   test_unrecognize_config();
+
+   return 0;
+}

test/variable_map_test.cpp

@@ -15,24 +15,12 @@ namespace po = boost::program_options;
 #include <boost/function.hpp>
 using namespace boost;
 
-#define BOOST_INCLUDE_MAIN  // for testing, include rather than link
-#include <boost/test/test_tools.hpp>
-
 #include <sstream>
 using namespace std;
 
-#define TEST_CHECK_THROW(expression, exception, description) \
-    try \
-    { \
-        expression; \
-        BOOST_ERROR(description);\
-        throw 10; \
-    } \
-    catch(exception &) \
-    { \
-    }
+#include "minitest.hpp"
 
-vector<string> sv(char* array[], unsigned size)
+vector<string> sv(const char* array[], unsigned size)
 {
     vector<string> r;
     for (unsigned i = 0; i < size; ++i)
@@ -45,24 +33,24 @@ void test_variable_map()
     options_description desc;
     desc.add_options()
         ("foo,f", new untyped_value)
-        ("bar,b", po::value<string>()->implicit())
-        ("biz,z", po::value<string>()->implicit())
+        ("bar,b", po::value<string>())
+        ("biz,z", po::value<string>())
         ("baz", new untyped_value())
         ("output,o", new untyped_value(), "")
         ;
-    char* cmdline3_[] = { "--foo='12'", "--bar=11", "-z3", "-ofoo" };
+    const char* cmdline3_[] = { "--foo='12'", "--bar=11", "-z3", "-ofoo" };
     vector<string> cmdline3 = sv(cmdline3_,
-                                 sizeof(cmdline3_)/sizeof(cmdline3_[0]));
+                                 sizeof(cmdline3_)/sizeof(const char*));
     parsed_options a3 = command_line_parser(cmdline3).options(desc).run();
     variables_map vm;
     store(a3, vm);
     notify(vm);
-    BOOST_CRITICAL_TEST(vm.size() == 4);
-    BOOST_TEST(vm["foo"].as<string>() == "'12'");
-    BOOST_TEST(vm["bar"].as<string>() == "11");
-    BOOST_TEST(vm.count("biz") == 1);
-    BOOST_TEST(vm["biz"].as<string>() == "3");
-    BOOST_TEST(vm["output"].as<string>() == "foo");
+    BOOST_REQUIRE(vm.size() == 4);
+    BOOST_CHECK(vm["foo"].as<string>() == "'12'");
+    BOOST_CHECK(vm["bar"].as<string>() == "11");
+    BOOST_CHECK(vm.count("biz") == 1);
+    BOOST_CHECK(vm["biz"].as<string>() == "3");
+    BOOST_CHECK(vm["output"].as<string>() == "foo");
 
     int i;
     desc.add_options()
@@ -70,19 +58,19 @@ void test_variable_map()
     ("zak", po::value<int>(&i), "")
     ("opt", bool_switch(), "");
 
-    char* cmdline4_[] = { "--zee", "--zak=13" };
+    const char* cmdline4_[] = { "--zee", "--zak=13" };
     vector<string> cmdline4 = sv(cmdline4_,
-                                 sizeof(cmdline4_)/sizeof(cmdline4_[0]));
+                                 sizeof(cmdline4_)/sizeof(const char*));
     parsed_options a4 = command_line_parser(cmdline4).options(desc).run();
 
     variables_map vm2;
     store(a4, vm2);
     notify(vm2);
-    BOOST_CRITICAL_TEST(vm2.size() == 3);
-    BOOST_TEST(vm2["zee"].as<bool>() == true);
-    BOOST_TEST(vm2["zak"].as<int>() == 13);
-    BOOST_TEST(vm2["opt"].as<bool>() == false);
-    BOOST_TEST(i == 13);
+    BOOST_REQUIRE(vm2.size() == 3);
+    BOOST_CHECK(vm2["zee"].as<bool>() == true);
+    BOOST_CHECK(vm2["zak"].as<int>() == 13);
+    BOOST_CHECK(vm2["opt"].as<bool>() == false);
+    BOOST_CHECK(i == 13);
 
     options_description desc2;
     desc2.add_options()
@@ -90,18 +78,40 @@ void test_variable_map()
     ("voo", po::value<string>())
     ("iii", po::value<int>()->default_value(123))
     ;
-    char* cmdline5_[] = {  "--voo=1" };
+    const char* cmdline5_[] = { "--voo=1" };
     vector<string> cmdline5 = sv(cmdline5_,
-                                 sizeof(cmdline5_)/sizeof(cmdline5_[0]));
+                                 sizeof(cmdline5_)/sizeof(const char*));
     parsed_options a5 = command_line_parser(cmdline5).options(desc2).run();
 
     variables_map vm3;
     store(a5, vm3);
     notify(vm3);
-    BOOST_CRITICAL_TEST(vm3.size() == 3);
-    BOOST_TEST(vm3["vee"].as<string>() == "42");
-    BOOST_TEST(vm3["voo"].as<string>() == "1");
-    BOOST_TEST(vm3["iii"].as<int>() == 123);
+    BOOST_REQUIRE(vm3.size() == 3);
+    BOOST_CHECK(vm3["vee"].as<string>() == "42");
+    BOOST_CHECK(vm3["voo"].as<string>() == "1");
+    BOOST_CHECK(vm3["iii"].as<int>() == 123);
+
+    options_description desc3;
+    desc3.add_options()
+    ("imp", po::value<int>()->implicit_value(100))
+    ("iim", po::value<int>()->implicit_value(200)->default_value(201))
+    ("mmp,m", po::value<int>()->implicit_value(123)->default_value(124))
+    ("foo", po::value<int>())
+    ;
+    /* The -m option is implicit. It does not have value in inside the token,
+       and we should not grab the next token.  */
+    const char* cmdline6_[] = {  "--imp=1", "-m", "--foo=1" };
+    vector<string> cmdline6 = sv(cmdline6_,
+                                 sizeof(cmdline6_)/sizeof(const char*));
+    parsed_options a6 = command_line_parser(cmdline6).options(desc3).run();
+
+    variables_map vm4;
+    store(a6, vm4);
+    notify(vm4);
+    BOOST_REQUIRE(vm4.size() == 4);
+    BOOST_CHECK(vm4["imp"].as<int>() == 1);
+    BOOST_CHECK(vm4["iim"].as<int>() == 201);
+    BOOST_CHECK(vm4["mmp"].as<int>() == 123);
 }
 
 int stored_value;
@@ -184,15 +194,15 @@ void test_priority()
     ("include", po::value< vector<int> >()->composing())
     ;
 
-    char* cmdline1_[] = { "--first=1", "--aux=10", "--first=3", "--include=1" };
+    const char* cmdline1_[] = { "--first=1", "--aux=10", "--first=3", "--include=1" };
     vector<string> cmdline1 = sv(cmdline1_, 
-                                 sizeof(cmdline1_)/sizeof(cmdline1_[0]));
+                                 sizeof(cmdline1_)/sizeof(const char*));
 
     parsed_options p1 = command_line_parser(cmdline1).options(desc).run();
 
-    char* cmdline2_[] = { "--first=12", "--second=7", "--include=7" };
+    const char* cmdline2_[] = { "--first=12", "--second=7", "--include=7" };
     vector<string> cmdline2 = sv(cmdline2_, 
-                                 sizeof(cmdline2_)/sizeof(cmdline2_[0]));
+                                 sizeof(cmdline2_)/sizeof(const char*));
 
     parsed_options p2 = command_line_parser(cmdline2).options(desc).run();
 
@@ -227,13 +237,54 @@ void test_priority()
     BOOST_CHECK_EQUAL(vm["include"].as< vector<int> >()[1], 7);
 }
 
+void test_multiple_assignments_with_different_option_description()
+{
+    // Test that if we store option twice into the same variable_map,
+    // and some of the options stored the first time are not present
+    // in the options descrription provided the second time, we don't crash.
+
+    options_description desc1("");    
+    desc1.add_options()
+        ("help,h", "")
+        ("includes", po::value< vector<string> >()->composing(), "");
+        ;
+
+    options_description desc2("");
+    desc2.add_options()
+        ("output,o", "");
+
+    vector<string> input1;
+    input1.push_back("--help");
+    input1.push_back("--includes=a");
+    parsed_options p1 = command_line_parser(input1).options(desc1).run();
+
+    vector<string> input2;
+    input1.push_back("--output");
+    parsed_options p2 = command_line_parser(input2).options(desc2).run();
+
+    vector<string> input3;
+    input3.push_back("--includes=b");
+    parsed_options p3 = command_line_parser(input3).options(desc1).run();
 
 
-int test_main(int, char* [])
+    variables_map vm;
+    store(p1, vm);
+    store(p2, vm);
+    store(p3, vm);
+
+    BOOST_REQUIRE(vm.count("help") == 1);
+    BOOST_REQUIRE(vm.count("includes") == 1);
+    BOOST_CHECK_EQUAL(vm["includes"].as< vector<string> >()[0], "a");
+    BOOST_CHECK_EQUAL(vm["includes"].as< vector<string> >()[1], "b");
+
+} 
+
+int main(int, char* [])
 {
     test_variable_map();
     test_semantic_values();
     test_priority();
+    test_multiple_assignments_with_different_option_description();
     return 0;
 }
 

test/winmain.cpp

@@ -3,30 +3,45 @@
 // (See accompanying file LICENSE_1_0.txt
 // or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-#ifdef _WIN32
+#if defined(_WIN32)
 #include <string>
 #include <vector>
 #include <cctype>
-
+#include <iostream>
+#include <stdlib.h>
 #include <boost/program_options/parsers.hpp>
+
+using namespace std;
 using namespace boost::program_options;
 
-#include <boost/test/test_tools.hpp>
+void check_equal(const std::vector<string>& actual, char **expected, int n)
+{
+    if (actual.size() != n)
+    {
+        std::cerr << "Size mismatch between expected and actual data\n";
+        abort();
+    }
+    for (int i = 0; i < n; ++i)
+    {
+        if (actual[i] != expected[i])
+        {
+            std::cerr << "Unexpected content\n";
+            abort();
+        }
+    }
+}
+
 #include <boost/preprocessor/cat.hpp>
 
 void test_winmain()
 {
-    using namespace std;
 
 #define C ,
 #define TEST(input, expected) \
     char* BOOST_PP_CAT(e, __LINE__)[] = expected;\
     vector<string> BOOST_PP_CAT(v, __LINE__) = split_winmain(input);\
-    BOOST_REQUIRE(BOOST_PP_CAT(v, __LINE__).size() == \
-            sizeof(BOOST_PP_CAT(e, __LINE__))/sizeof(char*));\
-    BOOST_CHECK_EQUAL_COLLECTIONS(BOOST_PP_CAT(v, __LINE__).begin(),\
-                                  BOOST_PP_CAT(v, __LINE__).end(),\
-                                  BOOST_PP_CAT(e, __LINE__));    
+    check_equal(BOOST_PP_CAT(v, __LINE__), BOOST_PP_CAT(e, __LINE__),\
+                sizeof(BOOST_PP_CAT(e, __LINE__))/sizeof(char*));    
 
 // The following expectations were obtained in Win2000 shell:
     TEST("1 ", {"1"});
@@ -45,13 +60,13 @@ void test_winmain()
     TEST("1\\\\1 ", {"1\\\\1"});    
 }
 
-int test_main(int, char*[])
+int main(int, char*[])
 {
     test_winmain();
     return 0;
 }
 #else
-int test_main(int, char*[])
+int main(int, char*[])
 {
     return 0;
 }