diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/Jamfile b/3rd_party_lib/boost_1_72_0/libs/program_options/Jamfile new file mode 100644 index 00000000..f0de2e0b --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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 ; diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/README.md b/3rd_party_lib/boost_1_72_0/libs/program_options/README.md new file mode 100644 index 00000000..b2bd595e --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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. diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/ci/build.sh b/3rd_party_lib/boost_1_72_0/libs/program_options/ci/build.sh new file mode 100755 index 00000000..49dd24ae --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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 $* diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/ci/codecov.sh b/3rd_party_lib/boost_1_72_0/libs/program_options/ci/codecov.sh new file mode 100755 index 00000000..2f7ea10f --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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" diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/ci/coverity.sh b/3rd_party_lib/boost_1_72_0/libs/program_options/ci/coverity.sh new file mode 100755 index 00000000..0de08a4c --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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" + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/ci/cppcheck.sh b/3rd_party_lib/boost_1_72_0/libs/program_options/ci/cppcheck.sh new file mode 100755 index 00000000..7734ffcc --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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' + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/ci/mingw.bat b/3rd_party_lib/boost_1_72_0/libs/program_options/ci/mingw.bat new file mode 100755 index 00000000..bc189fdb --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/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 +@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 \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/Jamfile.v2 b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/Jamfile.v2 new file mode 100644 index 00000000..22a680ef --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/Jamfile.v2 @@ -0,0 +1,23 @@ + +import toolset ; +toolset.using doxygen ; + +boostbook program_option + : program_options.xml + : autodoc + boost.root=../../../.. + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html + ; + +doxygen autodoc + : [ glob ../../../boost/program_options/*.hpp ] ; + +############################################################################### +alias boostdoc + : program_options.xml + : + : autodoc + : ; +explicit boostdoc ; +alias boostrelease ; +explicit boostrelease ; diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/acknowledgements.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/acknowledgements.xml new file mode 100644 index 00000000..e72e33c2 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/acknowledgements.xml @@ -0,0 +1,85 @@ + + + %entities; +]> +
+ Acknowledgements + + I'm very gratefull to all the people who helped with the development, + by discussion, fixes, and as users. It was pleasant + to see all that involvement, which made the library much better than it + would be otherwise. + + + In the early stages, the library was affected by discussions with + Gennadiy Rozental, William Kempf and Alexander Okhotin. + + + Hartmut Kaiser was the first person to try the library on his project + and send a number of suggestions and fixes. + + + The formal review lead to numerous comments and enhancements. Pavol + Droba helped with the option description semantic. Gennadiy Rozental has + criticised many aspects of the library which caused various simplifications. + Pavel Vozenilek did carefull review of the implementation. A number of + comments were made by: + + David Abrahams + Neal D. Becker + Misha Bergal + James Curran + Carl Daniel + Beman Dawes + Tanton Gibbs + Holger Grund + Hartmut Kaiser + Petr Kocmid + Baptiste Lepilleur + Marcelo E. Magallon + Chuck Messenger + John Torjo + Matthias Troyer + + + + Doug Gregor and Reece Dunn helped to resolve the issues with Boostbook + version of the documentation. + + + Even after review, a number of people have helped with further development: + + Rob Lievaart + Thorsten Ottosen + Joseph Wu + Ferdinand Prantl + Miro Jurisic + John Maddock + Janusz Piwowarski + Charles Brockman + Jonathan Wakely + + + + + + + + + + + + +
+ + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/alternatives b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/alternatives new file mode 100644 index 00000000..9782e057 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/alternatives @@ -0,0 +1,43 @@ + +CLI (part of the Jarakta project) +http://jakarta.apache.org/commons/cli/index.html + +This is Java library. +The interface seems to be similiar, except for data storage. +1. Instead of variables_map, the library can store the data +as Java system properties. +2. The class Option, which uses to describe the data, is also + used to keep the value. In contract, I keep them in separate + place. This facilitate using the same options description + for different data sources. + +TODO: Need to check that Option.setType method does. + +Werken.opt +http://sourceforge.net/projects/werken-opt/ + +This is a much simpler library then CLI, which +somewhat less features. + +JArgs +http://jargs.sourceforge.net/ + +Another Java library. Has a fixed set of value types it can +handle. + +Options (by Brad Appleton) +http://www.enteract.com/~bradapp/ftp/src/libs/C++/Options.html + +This is very lean library. It does not provide argument validation, +and the only iterface is iteration over arguments. An interesting +iterface decision is using chars to identify presense of option's parameters. +This may be moved to my library (|, :, ?, *, +) + +Cmdline (by Brad Appleton) +http://www.enteract.com/~bradapp/ftp/src/libs/C++/CmdLine.html + +This library provides options validation and storage. Unfortunately +1. Only a fixed set of data types is supported. +2. It's intrusive -- one has to declare variable of "class ArgChar" or +something, and then extract data from there. + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/autodoc.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/autodoc.xml new file mode 100644 index 00000000..f09cf6ad --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/autodoc.xml @@ -0,0 +1,592 @@ + +
+ + + += 1Allow "--long_name" style. = allow_long << 1Allow "-<single character" style. = allow_short << 1Allow "-" in short options. = allow_dash_for_short << 1Allow "/" in short options. = allow_slash_for_short << 1Allow option parameter in the same token for long option, like in --foo=10 = long_allow_adjacent << 1Allow option parameter in the next token for long options. = long_allow_next << 1Allow option parameter in the same token for short options. = short_allow_adjacent << 1Allow option parameter in the next token for short options. = short_allow_next << 1Allow to merge several short options together, so that "-s -k" become "-sk". All of the options but last should accept no parameter. For example, if "-s" accept a parameter, then "k" will be taken as parameter, not another short option. Dos-style short options cannot be sticky. = allow_sticky << 1Allow abbreviated spellings for long options, if they unambiguously identify long option. No long option name should be prefix of other long option name if guessing is in effect. = allow_guessing << 1Ignore the difference in case for long options. = long_case_insensitive << 1Ignore the difference in case for short options. = (long_case_insensitive | short_case_insensitive)Ignore the difference in case for all options. = short_case_insensitive << 1Allow long options with single option starting character, e.g -foo=10 = (allow_short | short_allow_adjacent | short_allow_next + | allow_long | long_allow_adjacent | long_allow_next + | allow_sticky | allow_guessing + | allow_dash_for_short)The more-or-less traditional unix style. = unix_styleThe default style. Various possible styles of options.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 options is also configurable.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 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. + + + + + + + + + + + + + + + + + + + + + + +
+
+ +
+
+ +boost::eof_iterator< environment_iterator, std::pair< std::string, std::string > > +void + +char ** + + +
+
+ +iterator_facade< Derived, const ValueType, forward_traversal_tag >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 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 only if both have their 'eof' bits set. The 'get' method either obtains the new value or sets the 'eof' bit.Specifically, derived class should define: +A default constructor, which creates iterator with 'eof' bit set. The constructor body should call 'found_eof' method defined here. +Some other constructor. It should initialize some 'data pointer' used in iterator operation and then call 'get'. +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' 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. + + + +ValueType &Returns the reference which should be used by derived class to store the next value. +voidShould be called by derived class to indicate that it can't produce next element. + + +void +boolconst eof_iterator & +const ValueType & + + +
+
+ + +boost::program_options::error_with_no_option_nameClass thrown when there's ambiguity amoung several possible options. +const std::vector< std::string > & + +const std::vector< std::string > & + + +voidconst std::string &Makes all substitutions using the template + +logic_errorBase class for all errors in the library. + +const std::string & +boost::program_options::error_with_option_nameBase 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 parameterHaving 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! +voidconst std::string &Does NOT set option name, because no option name makes sense + +const std::string &const std::string &"" + +boost::program_options::errorBase class for most exceptions in the library.Substitutes the values for the parameter name placeholders in the template to create the human readable error messagePlaceholders are surrounded by % signs: example% Poor man's version of boost::formatIf 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) std::stringtemplate with placeholders + +voidconst std::string &const std::string &Substitute parameter_name->value to create the error message from the error template +voidconst std::string &const std::string &const std::string &If the parameter is missing, then make the from->to substitution instead +voidconst std::string &const std::string &intAdd context to an exception +voidint +voidconst std::string &Overridden in error_with_no_option_name +std::string +voidconst std::string & +const char *Creates the error_message on the fly Currently a thin wrapper for substitute_placeholders() + +const std::string &const std::string &""const std::string &""int0 +gcc says that throw specification on dtor is loosened without this line + +voidconst std::string &Makes all substitutions using the template +voidconst std::string &const std::string & +std::stringConstruct option name in accordance with the appropriate prefix style: i.e. long dash or short slash etc +std::string + +boost::program_options::validation_errorClass thrown if there is an invalid bool value given + +const std::string & +boost::program_options::errorClass thrown when there are programming error related to style + +const std::string & +boost::program_options::invalid_syntaxClass thrown when there are syntax errors in given command line + +kind_tconst std::string &""const std::string &""int0 + +boost::program_options::invalid_syntax +std::stringConvenience functions for backwards compatibility + +const std::string &kind_t + +boost::program_options::validation_errorClass thrown if there is an invalid option value given + +const std::string & +const std::wstring & +boost::program_options::error_with_option_nameClass thrown when there's syntax error either for command line or config file options. See derived children for concrete classes. = 30 + +kind_t +std::stringConvenience functions for backwards compatibility + +kind_tconst std::string &""const std::string &""int0 + + +std::stringkind_tUsed to convert kind_t to a related error text + +boost::program_options::error_with_option_nameClass thrown when there are several occurrences of an option, but user called a method which cannot return them all. + + + +boost::program_options::error_with_option_nameClass thrown when there are several option values, but user called a method which cannot return them all. + + + +boost::program_options::errorClass thrown if config file can not be read + +const char * +boost::program_options::error_with_option_nameClass thrown when a required/mandatory option is missing + +const std::string & + +boost::program_options::errorClass thrown when there are too many positional options. This is a programming error. + + +boost::program_options::error_with_no_option_nameClass thrown when option name is not recognized. + +const std::string &"" + +boost::program_options::error_with_option_nameClass thrown when value of option is incorrect. = 30 + +kind_t + +kind_tconst std::string &""const std::string &""int0 + + +std::stringkind_tUsed to convert kind_t to a related error text + + + + + + + + + + + + + + + + + + + +std::stringconst std::string & + + +
+
+ + +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 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. std::stringString key of this option. Intentionally independent of the template parameter. +intPosition key of this option. All options without an explicit name are sequentially numbered starting from 0. If an option has explicit name, 'position_key' is equal to -1. It is possible that both position_key and string_key is specified, in case name is implicitly added. +std::vector< std::basic_string< charT > >Option's value +std::vector< std::basic_string< charT > >The original unchanged tokens this option was created from. +boolTrue 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. +boolTrue if string_key has to be handled case insensitive. + + + +const std::string &const std::vector< std::string > & +basic_option< char > +basic_option< wchar_t > + + + + + + + + + + + + + + + + + + + + + +
+
+ + +boost::program_options::errorClass thrown when duplicate option description is found. + +const std::string & +Describes one possible command line/config file option. There are two kinds of properties of an option. First describe it syntactically and 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. See Also:options_description + + + +match_resultconst std::string &boolboolboolGiven 'option', specified in the input source, returns 'true' if 'option' specifies *this. +const std::string &const std::string &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 '-'. +std::stringint0Returns 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. +const std::string & +const std::pair< const std::string *, std::size_t > +const std::string &Explanation of this option. +shared_ptr< const value_semantic >Semantic of option's value. +std::stringReturns the option name, formatted suitably for usage message. +std::stringReturns the parameter name and properties, formatted suitably for usage message. + + +const char *const value_semantic *Initializes the object with the passed data.Note: it would be nice to make the second parameter auto_ptr, to explicitly pass ownership. Unfortunately, it's often needed to create objects of types derived from 'value_semantic': options_description d; d.add_options()("a", parameter<int>("n")->default_value(1)); Here, the static type returned by 'parameter' should be derived from value_semantic.Alas, derived->base conversion for auto_ptr does not really work, see 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#84So, we have to use plain old pointers. Besides, users are not expected to use the constructor directly.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 -- short name. + + +const char *const value_semantic *const char *Initializes the class with the passed data. + + +option_description &const char * + +A set of option descriptions. This provides convenient interface for adding new option (the add_options) method, and facilities to search for options by name.See here for option adding interface discussion. See Also:option_description + +const unsigned + +voidshared_ptr< option_description >Adds new variable description. Throws duplicate_variable_error if either short or long name matches that of already present one. +options_description &const options_description &Adds a group of option description. This has the same effect as adding all option_descriptions in 'desc' individually, except that output operator will show a separate group. Returns *this. +unsignedFind the maximum width of the option column, including options in groups. +options_description_easy_initReturns an object of implementation-defined type suitable for adding options to options_description. The returned object will have overloaded operator() with parameter type matching 'option_description' constructors. Calling the operator will create new option_description instance and add it. +const option_description &const std::string &boolboolfalseboolfalse +const option_description *const std::string &boolboolfalseboolfalse +const std::vector< shared_ptr< option_description > > & +voidstd::ostream &unsigned0Outputs 'desc' to the specified stream, calling 'f' to output each option_description element. + +unsignedm_default_line_lengthunsignedm_default_line_length/2Creates the instance. +const std::string &unsignedm_default_line_lengthunsignedm_default_line_length/2Creates 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. + +friend BOOST_PROGRAM_OPTIONS_DECL std::ostream &std::ostream &const options_description &Produces a human readable output of 'desc', listing options, their descriptions and allowed parameters. Other options_description instances previously passed to add will be output separately. + +Class which provides convenient creation syntax to option_description. +options_description_easy_init &const char *const char * +options_description_easy_init &const char *const value_semantic * +options_description_easy_init &const char *const value_semantic *const char * + +options_description * + + + + + + + + + + + + + + + + + + + + + +
+
+ + +cmdlineCommand line parser.The class allows one to specify all the information needed for parsing 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 number of parameters will be confusing.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. +basic_command_line_parser &const options_description &Sets options descriptions to use. +basic_command_line_parser &const positional_options_description &Sets positional options description to use. +basic_command_line_parser &intSets the command line style. +basic_command_line_parser &ext_parserSets the extra parsers. +basic_parsed_options< charT >Parses the options and returns the result of parsing. Throws on error. +basic_command_line_parser &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 &style_parser + +const std::vector< std::basic_string< charT > > &Creates a command line parser for the specified arguments list. The 'args' parameter should not include program name. +intconst charT *constCreates a command line parser for the specified arguments list. The parameters should be the same as passed to 'main'. +wchar_tSpecialization of basic_parsed_options which: +provides convenient conversion from basic_parsed_options<char> +stores the passed char-based options for later use. + +std::vector< basic_option< wchar_t > > +const options_description * +basic_parsed_options< char >Stores UTF8 encoded options that were passed to constructor, to avoid reverse conversion in some cases. +intMainly 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 + + +const basic_parsed_options< char > &Constructs wrapped options from options in UTF8 encoding. +Controls if the 'collect_unregistered' function should include positional options, or not. +basic_parsed_options< char > +basic_parsed_options< wchar_t > +Augments basic_parsed_options<wchar_t> with conversion from 'parsed_options' function1< std::pair< std::string, std::string >, const std::string & > +basic_command_line_parser< char > +basic_command_line_parser< wchar_t > + + + + + + + + + +basic_parsed_options< charT >intconst charT *constconst options_description &int0function1< std::pair< std::string, std::string >, const std::string & >ext_parser()Creates instance of 'command_line_parser', passes parameters to it, and returns the result of calling the 'run' method. +BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options< charT >std::basic_istream< charT > &const options_description &boolfalseParse a config file.Read from given stream. +BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options< charT >const char *const options_description &boolfalseParse a config file.Read from file with the given name. The character type is passed to the file stream. +std::vector< std::basic_string< charT > >const std::vector< basic_option< charT > > &enum collect_unrecognized_modeCollects 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. +BOOST_PROGRAM_OPTIONS_DECL parsed_optionsconst options_description &const function1< std::string, std::string > &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.This is done since naming of environment variables is typically different from the naming of command line options. +BOOST_PROGRAM_OPTIONS_DECL parsed_optionsconst options_description &const std::string &Parse environment.Takes all environment variables which start with 'prefix'. The option name is obtained from variable name by removing the prefix and converting the remaining string into lower case. +BOOST_PROGRAM_OPTIONS_DECL parsed_optionsconst options_description &const char *This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 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 std::vector< std::string >const std::string &const std::string &" \t"const std::string &"'\""const std::string &"\\"BOOST_PROGRAM_OPTIONS_DECL std::vector< std::wstring >const std::wstring &const std::wstring &L" \t"const std::wstring &L"'\""const std::wstring &L"\\"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 '\' + + + + +
+
+ + +Describes positional options.The class allows to guess option names for positional options, which are specified on the command line and are identified by the position. The class uses the information provided by the user to associate a name with every positional option, or tell that no name is known.The primary assumption is that only the relative order of the positional options themselves matters, and that any interleaving ordinary options don't affect interpretation of positional options.The user initializes the class by specifying that first N positional options should be given the name X1, following M options should be given the name X2 and so on. +positional_options_description &const char *intSpecies that up to 'max_count' next positional options should be given the 'name'. The value of '-1' means 'unlimited'. No calls to 'add' can be made after call with 'max_value' equal to '-1'. +unsignedReturns the maximum number of positional options that can be present. Can return (numeric_limits<unsigned>::max)() to indicate unlimited number. +const std::string &unsignedReturns the name that should be associated with positional options at 'position'. Precondition: position < max_total_count() + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + +boost::program_options::value_semantic_codecvt_helper< charT >boost::program_options::typed_value_baseClass which handles value of a specific type. +typed_value *const T &Specifies default value, which will be used if none is explicitly specified. The type 'T' should provide operator<< for ostream. +typed_value *const T &const std::string &Specifies default value, which will be used if none is explicitly specified. 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 *const T &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 *const std::string &Specifies the name used to to the value in help message. +typed_value *const T &const std::string &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 *function1< void, const T & >Specifies a function to be called when the final value is determined. +typed_value *Specifies that the value is composing. See the 'is_composing' method for explanation. +typed_value *Specifies that the value can span multiple tokens. +typed_value *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 *Specifies that the value must occur. +std::string +bool +unsigned +unsigned +bool +voidboost::any &const std::vector< std::basic_string< charT > > &Creates an instance of the 'validator' class and calls its operator() to perform the actual conversion. +boolboost::any &If default value was specified via previous call to 'default_value', stores that value into 'value_store'. Returns true if default value was stored. +voidconst boost::any &If an address of variable to store value was specified when creating *this, stores the value there. Otherwise, does nothing. +const std::type_info & + +T *Ctor. The 'store_to' parameter tells where to store the value when it's known. The parameter can be NULL. +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. +const std::type_info & + + +boost::program_options::value_semantic_codecvt_helper< char >Class which specifies a simple handling of a value: the value will have string type and only one token is allowed. +std::stringReturns the name of the option. The name is only meaningful for automatic help message. +unsignedThe minimum number of tokens for this option that should be present on the command line. +unsignedThe maximum number of tokens for this option that should be present on the command line. +boolReturns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded. +boolReturns true if value must be given. Non-optional value +voidboost::any &const std::vector< std::string > &If 'value_store' is already initialized, or new_tokens has more than one elements, throws. Otherwise, assigns the first string from 'new_tokens' to 'value_store', without any modifications. +boolboost::any &Does nothing. +voidconst boost::any &Does nothing. + +boolfalse +Class which specifies how the option's value is to be parsed and converted into C++ types. +std::stringReturns the name of the option. The name is only meaningful for automatic help message. +unsignedThe minimum number of tokens for this option that should be present on the command line. +unsignedThe maximum number of tokens for this option that should be present on the command line. +boolReturns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded. +boolReturns true if value must be given. Non-optional value +voidboost::any &const std::vector< std::string > &boolParses a group of tokens that specify a value of option. Stores the result in 'value_store', using whatever representation is desired. May be be called several times if value of the same option is specified more than once. +boolboost::any &Called to assign default value to 'value_store'. Returns true if default value is assigned, and false if no default value exists. +voidconst boost::any &Called when final value of an option is determined. + + +Helper class which perform necessary character conversions in the 'parse' method and forwards the data further. charboost::program_options::value_semanticHelper 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. +voidboost::any &const std::vector< std::string > &boolParses a group of tokens that specify a value of option. Stores the result in 'value_store', using whatever representation is desired. May be be called several times if value of the same option is specified more than once. + + +voidboost::any &const std::vector< std::string > & + +wchar_tboost::program_options::value_semanticHelper 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. +voidboost::any &const std::vector< std::string > &boolParses a group of tokens that specify a value of option. Stores the result in 'value_store', using whatever representation is desired. May be be called several times if value of the same option is specified more than once. + + +voidboost::any &const std::vector< std::wstring > & + + + + +typed_value< T > *typed_value< T > *T *Creates a typed_value<T> instance. This function is the primary method to create value_semantic instance for a specific type, which can later be passed to 'option_description' constructor. The second overload is used when it's additionally desired to store the value of option into program variable. + +typed_value< T, wchar_t > *typed_value< T, wchar_t > *T *Creates a typed_value<T> instance. This function is the primary method to create value_semantic instance for a specific type, which can later be passed to 'option_description' constructor. + +BOOST_PROGRAM_OPTIONS_DECL typed_value< bool > *BOOST_PROGRAM_OPTIONS_DECL typed_value< bool > *bool *Works the same way as the 'value<bool>' function, but the created value_semantic won't accept any explicit value. So, if the option is present on the command line, the value will be 'true'. + + + + + + + + + + + + + +
+
+ + +Implements string->string mapping with convenient value casting facilities. +const variable_value &const std::string &Obtains the value of variable 'name', from *this and possibly from the chain of variable maps. +if there's no value in *this. +if there's next variable map, returns value from it +otherwise, returns empty value + + +if there's defaulted value +if there's next variable map, which has a non-defaulted value, return that +otherwise, return value from *this + + +if there's a non-defaulted value, returns it. + + +voidabstract_variables_map *Sets next variable map, which will be used to find variables not found in *this. + + +const abstract_variables_map * + + +const variable_value &const std::string &Returns value of variable 'name' stored in *this, or empty value otherwise. + +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. + +const options_description *int0 +Class holding value of option. Contains details about how the value is set and allows to conveniently obtain the value. +friend BOOST_PROGRAM_OPTIONS_DECL voidconst basic_parsed_options< char > &variables_map &boolStores 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. + + +const T &If stored value if of type T, returns that value. Otherwise, throws boost::bad_any_cast exception. +T &This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. +boolReturns true if no value is stored. +boolReturns true if the value was not explicitly given, but has default value. +const boost::any &Returns the contained value. +boost::any &Returns the contained value. + + +const boost::any &bool +boost::program_options::abstract_variables_mapstd::map< std::string, variable_value >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. +const variable_value &const std::string & +void +void + + +const abstract_variables_map * + +const variable_value &const std::string &Implementation of abstract_variables_map::get which does 'find' in *this. + + +friend BOOST_PROGRAM_OPTIONS_DECL voidconst basic_parsed_options< char > &variables_map &boolStores 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 voidconst basic_parsed_options< char > &variables_map &boolfalseStores 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 voidconst basic_parsed_options< wchar_t > &variables_map &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 voidvariables_map &Runs all 'notify' function for options in 'm'. + + + + + + + + + + + + + + + + + + +
+
+The version of the source interface. The value will be incremented whenever a change is made which might cause compilation errors for existing code. + +
+ \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/changes.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/changes.xml new file mode 100644 index 00000000..5bd9ca27 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/changes.xml @@ -0,0 +1,150 @@ + + + %entities; +]> +
+ Changes since formal review + + During formal review, a large number of changes was suggested. To make + using the new version easier, the implemented changes are described + below. + + Let's start with an example. The following is a typical code for the + reviewed version: + options_description desc; + desc.add_options() + ("magic", parameter<int>("value"), "magic value for the program") + .default_value("43") + + variables_map vm; + options_and_arguments oa1 = parse_command_line(ac, av, desc); + store(oa1, vm, desc) + + variables_map vm2; + ifstream ifs("main.cfg"); + options_and_arguments oa2 = parse_config_file(ifs, desc); + store(oa1, vm2, desc); + + vm.next(&vm2); + The code for the current version would look like: + + options_description desc; + desc.add_options() + ("magic", value<int>()->default_value(43), + "magic value for the program") + + variables_map vm; + + store(parse_command_line(ac, av, desc), vm); + + ifstream ifs("main.cfg"); + store(parse_command_line(ifs, desc), vm); + + notify(vm); + + + + Let's examine all the changes in detail + +
+ Option description + + + + The parameter function was renamed to + value. Rationale: "paramater" is yet another term with no + clear definition, while "value" is already used everywhere in + docs. + + + The default value is specified in different place, and should + use the value of desired type, not string. Previous code was: + + ("magic", parameter<int>("value")).default_value("43") + + and the new code is + + ("magic", parameter<int>("value")->default_value(43)); + + Rationale: the new way is less restrictive. At the same time, the + new design allows to implement other behaviour, like validation of + the value, which require knowledge of the value type. + + + + + The number of token value can take on command line, which was + specified using character suffix appended to value name, is now + specified using more explicit member calls. Moreover, it's not longer + possible to specify the "value name". + For example: +("numbers", parameter<int>("n+")) + has became +("numbers", value<int>()->multitoken()) + Rationale: such modifiers tend to make command line usage less + clear. There's no need to make evil things too easy to do. + The "value name" had only two roles: specifying modifiers, and + telling what to output in automated help. The first role has became + obsolete, and the second was questionable too. It was very unclear how + to decide on the best "value name", and eventually the selection was randon. + + + + +
+ +
+ Parsers + + + + + The options_and_argument class was removed. + + + The cmdline and config_file classes + were removed from the public interface. Various command line styles + are now declared in the command_line_style subnamespace. + + + + + New function parse_environment was added. + + + + Support for positional options was added + + + +
+ + +
+ Storage + + + + The notify function should be called after all + sources are stored in a variales_map instance. This is + done to property support priority of configuration sources. + + + +
+ + + +
+ + \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/design.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/design.xml new file mode 100644 index 00000000..0881500b --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/design.xml @@ -0,0 +1,213 @@ + + + %entities; +]> +
+ Design Discussion + + This section focuses on some of the design questions. + + +
+ + Unicode Support + + Unicode support was one of the features specifically requested + during the formal review. Throughout this document "Unicode support" is + a synonym for "wchar_t" support, assuming that "wchar_t" always uses + Unicode encoding. Also, when talking about "ascii" (in lowercase) we'll + not mean strict 7-bit ASCII encoding, but rather "char" strings in local + 8-bit encoding. + + + + Generally, "Unicode support" can mean + many things, but for the program_options library it means that: + + + + Each parser should accept either char* + or wchar_t*, correctly split the input into option + names and option values and return the data. + + + + For each option, it should be possible to specify whether the conversion + from string to value uses ascii or Unicode. + + + + The library guarantees that: + + + ascii input is passed to an ascii value without change + + + + Unicode input is passed to a Unicode value without change + + + 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). + + + + + + + + + The important point is that it's possible to have some "ascii + options" together with "Unicode options". There are two reasons for + this. First, for a given type you might not have the code to extract the + value from Unicode string and it's not good to require that such code be written. + Second, imagine a reusable library which has some options and exposes + options description in its interface. If all + options are either ascii or Unicode, and the library does not use any + 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. + + + Another important point is that ascii strings are passed though + without modification. In other words, it's not possible to just convert + ascii to Unicode and process the Unicode further. The problem is that the + default conversion mechanism -- the codecvt facet -- might + not work with 8-bit input without additional setup. + + + The Unicode support outlined above is not complete. For example, we + 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 + complexities. E.g. if option names depend on current locale, then all + program parts and other parts which use the name must be + internationalized too. + + + The primary question in implementing the Unicode support is whether + to use templates and std::basic_string or to use some + internal encoding and convert between internal and external encodings on + the interface boundaries. + + + The choice, mostly, is between code size and execution + speed. A templated solution would either link library code into every + application that uses the library (thereby making shared library + impossible), or provide explicit instantiations in the shared library + (increasing its size). The solution based on internal encoding would + necessarily make conversions in a number of places and will be somewhat slower. + Since speed is generally not an issue for this library, the second + solution looks more attractive, but we'll take a closer look at + individual components. + + + For the parsers component, we have three choices: + + + Use a fully templated implementation: given a string of a + certain type, a parser will return a &parsed_options; instance + with strings of the same type (i.e. the &parsed_options; class + will be templated). + + + Use internal encoding: same as above, but strings will be converted to and + from the internal encoding. + + + Use and partly expose the internal encoding: same as above, + but the strings in the &parsed_options; instance will be in the + internal encoding. This might avoid a conversion if + &parsed_options; instance is passed directly to other components, + but can be also dangerous or confusing for a user. + + + + + + The second solution appears to be the best -- it does not increase + the code size much and is cleaner than the third. To avoid extra + conversions, the Unicode version of &parsed_options; can also store + strings in internal encoding. + + + For the options descriptions component, we don't have much + choice. Since it's not desirable to have either all options use ascii or all + of them use Unicode, but rather have some ascii and some Unicode options, the + interface of the &value_semantic; must work with both. The only way is + to pass an additional flag telling if strings use ascii or internal encoding. + The instance of &value_semantic; can then convert into some + other encoding if needed. + + + For the storage component, the only affected function is &store;. + For Unicode input, the &store; function should convert the value to the + internal encoding. It should also inform the &value_semantic; class + about the used encoding. + + + Finally, what internal encoding should we use? The + alternatives are: + std::wstring (using UCS-4 encoding) and + std::string (using UTF-8 encoding). The difference between + alternatives is: + + + Speed: UTF-8 is a bit slower + + + Space: UTF-8 takes less space when input is ascii + + + Code size: UTF-8 requires additional conversion code. However, + it allows one to use existing parsers without converting them to + std::wstring and such conversion is likely to create a + number of new instantiations. + + + + + There's no clear leader, but the last point seems important, so UTF-8 + will be used. + + + 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: + + + We need to assume the character literals use ascii encoding + and that inputs use Unicode encoding. + + + A Unicode character (say '=') can be followed by 'composing + character' and the combination is not the same as just '=', so a + simple search for '=' might find the wrong character. + + + + Neither of these issues appear to be critical in practice, since ascii is + almost universal encoding and since composing characters following '=' (and + other characters with special meaning to the library) are not likely to appear. + + +
+ + +
+ + \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/glossary.dox b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/glossary.dox new file mode 100644 index 00000000..8a410eff --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/glossary.dox @@ -0,0 +1,19 @@ +/** @page glossary Glosary + +
+
Token
A single whitespace-separated part of + command line. In other words, an element of argv array.
+ +
Option
No definition yet. Options typically correspond to + (name, value) pair. Then can spawn several tokens.
+ +
Argument
No definition yet.
+ +
Command line element
A complete part of command line. May + be either option or argument.
+ +
Parameter
The syntantic element which specify value of the + option
+ +
+*/ \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/glossary.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/glossary.xml new file mode 100644 index 00000000..c9ed7282 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/glossary.xml @@ -0,0 +1,48 @@ + + + Glossary + + + Token + + A single whitespace-separated part of + command line. In other words, an element of argv array. + + + + + + Option + + No definition yet. Options typically correspond to + (name, value) pair. Then can spawn several tokens. + + + + + + Argument + + No definition yet. + + + + + + Command line element + + A complete part of command line. May + be either option or argument. + + + + + + Parameter + + The syntactic element which specify value of an + option. + + + + \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/howto.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/howto.xml new file mode 100644 index 00000000..0841c9f1 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/howto.xml @@ -0,0 +1,499 @@ + + + %entities; +]> +
+ + How To + + This section describes how the library can be used in specific + situations. + + +
+ Non-conventional Syntax + + 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. + + + additional parser + For such cases, the library allows the user to provide an + additional parser -- a function which will be called on each + command line element, before any processing by the library. If the + additional parser recognises the syntax, it returns the option name and + value, which are used directly. The above example can be handled by the + following code: + + + + +pair<string, string> reg_foo(const string& s) +{ + if (s.find("-f") == 0) { + if (s.substr(2, 3) == "no-") + return make_pair(s.substr(5), string("false")); + else + return make_pair(s.substr(2), string("true")); + } else { + return make_pair(string(), string()); + } +} + + Here's the definition of the additional parser. When parsing the command + line, we pass the additional parser: + +store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo) + .run(), vm); + + The complete example can be found in the "example/custom_syntax.cpp" + file. + +
+ +
+ Response Files + + response files + + Some operating system have very low limits of the command line + length. The common way to work around those limitations is using + response files. A response file is just a + configuration file which uses the same syntax as the command line. If + the command line specifies a name of response file to use, it's loaded + and parsed in addition to the command line. The library does not + provide direct support for response files, so you'll need to write some + extra code. + + + + First, you need to define an option for the response file: + +("response-file", value<string>(), + "can be specified with '@name', too") + + + + Second, you'll need an additional parser to support the standard syntax + for specifying response files: "@file": + at_option_parser(string const&s) +{ + if ('@' == s[0]) + return std::make_pair(string("response-file"), s.substr(1)); + else + return pair(); +} +]]> + + + + Finally, when the "response-file" option is found, you'll have to + load that file and pass it to the command line parser. This part is the + hardest. We'll use the Boost.Tokenizer library, which works but has some + limitations. You might also consider Boost.StringAlgo. The code is: +().c_str()); + if (!ifs) { + cout << "Could not open the response file\n"; + return 1; + } + // Read the whole file into a string + stringstream ss; + ss << ifs.rdbuf(); + // Split the file content + char_separator sep(" \n\r"); + std::string ResponsefileContents( ss.str() ); + tokenizer > tok(ResponsefileContents, sep); + vector 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); +} +]]> + + The complete example can be found in the "example/response_file.cpp" + file. + + +
+ +
+ Winmain Command Line + + On the Windows operating system, GUI applications receive the + command line as a single string, not split into elements. For that reason, + the command line parser cannot be used directly. At least on some + 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 + split_winmain function is a portable mechanism provided + by the library. + + Here's an example of use: + +vector<string> args = split_winmain(lpCmdLine); +store(command_line_parser(args).options(desc).run(), vm); + + The split_winmain function is overloaded for wchar_t strings, so can + also be used in Unicode applications. + + +
+ +
+ Option Groups and Hidden Options + + Having a single instance of the &options_description; class with all + the program's options can be problematic: + + + Some options make sense only for specific source, for example, + configuration files. + + + The user would prefer some structure in the generated help message. + + + Some options shouldn't appear in the generated help message at all. + + + + + To solve the above issues, the library allows a programmer to create several + instances of the &options_description; class, which can be merged in + different combinations. The following example will define three groups of + options: command line specific, and two options group for specific program + modules, only one of which is shown in the generated help message. + + + Each group is defined using standard syntax. However, you should + use reasonable names for each &options_description; instance: +(), + "produce a help for a given module") + ("version", "output the version number") + ; + +options_description gui("GUI options"); +gui.add_options() + ("display", value(), "display to use") + ; + +options_description backend("Backend options"); +backend.add_options() + ("num-threads", value(), "the initial number of threads") + ; +]]> + + + After declaring options groups, we merge them in two + combinations. The first will include all options and be used for parsing. The + second will be used for the "--help" option. + +// Declare an options description instance which will include +// all the options +options_description all("Allowed options"); +all.add(general).add(gui).add(backend); + +// Declare an options description instance which will be shown +// to the user +options_description visible("Allowed options"); +visible.add(general).add(gui); + + + + What is left is to parse and handle the options: +(); + if (s == "gui") { + cout << gui; + } else if (s == "backend") { + cout << backend; + } else { + cout << "Unknown module '" + << s << "' in the --help-module option\n"; + return 1; + } + return 0; +} +if (vm.count("num-threads")) { + cout << "The 'num-threads' options was set to " + << vm["num-threads"].as() << "\n"; +} +]]> + When parsing the command line, all options are allowed. The "--help" + message, however, does not include the "Backend options" group -- the + options in that group are hidden. The user can explicitly force the + display of that options group by passing "--help-module backend" + option. The complete example can be found in the + "example/option_groups.cpp" file. + + +
+ +
+ Custom Validators + + By default, the conversion of option's value from string into C++ + type is done using iostreams, which sometimes is not convenient. The + library allows the user to customize the conversion for specific + classes. In order to do so, the user should provide suitable overload of + the validate function. + + + + Let's first define a simple class: + and then overload the validate function: +& values, + magic_number* target_type, int) +{ + static regex r("\\d\\d\\d-(\\d\\d\\d)"); + + using namespace boost::program_options; + + // Make sure no previous assignment to 'a' was made. + 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 + // int. + smatch match; + if (regex_match(s, match, r)) { + v = any(magic_number(lexical_cast(match[1]))); + } else { + throw validation_error(validation_error::invalid_option_value); + } +} +]]> +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 magic_number class. The second is the list of strings + found in the next occurrence of the option. The remaining two parameters + are needed to workaround the lack of partial template specialization and + partial function template ordering on some compilers. + + + The function first checks that we don't try to assign to the same + option twice. Then it checks that only a single string was passed + in. Next the string is verified with the help of the Boost.Regex + library. If that test is passed, the parsed value is stored into the + v variable. + + + The complete example can be found in the "example/regex.cpp" file. + + + +
+ +
+ Unicode Support + + To use the library with Unicode, you'd need to: + + + Use Unicode-aware parsers for Unicode input + + + Require Unicode support for options which need it + + + + + Most of the parsers have Unicode versions. For example, the + &parse_command_line; function has an overload which takes + wchar_t strings, instead of ordinary char. + + + Even if some of the parsers are Unicode-aware, it does not mean you + need to change definition of all the options. In fact, for many options, + like integer ones, it makes no sense. To make use of Unicode you'll need + some Unicode-aware options. They are different from + ordinary options in that they accept wstring input, and + process it using wide character streams. Creating an Unicode-aware option + is easy: just use the the wvalue function instead of the + regular value. + + + When an ascii parser passes data to an ascii option, or a Unicode + parser passes data to a Unicode option, the data are not changed at + all. So, the ascii option will see a string in local 8-bit encoding, and + the Unicode option will see whatever string was passed as the Unicode + input. + + + What happens when Unicode data is passed to an ascii option, and + vice versa? The library automatically performs the conversion from + Unicode to local 8-bit encoding. For example, if command line is in + ascii, but you use wstring options, then the ascii input + will be converted into Unicode. + + + To perform the conversion, the library uses the codecvt<wchar_t, + char> locale facet from the global locale. If + you want to work with strings that use local 8-bit encoding (as opposed to + 7-bit ascii subset), your application should start with: + +locale::global(locale("")); + + which would set up the conversion facet according to the user's selected + locale. + + + It's wise to check the status of the C++ locale support on your + implementation, though. The quick test involves three steps: + + + Go the the "test" directory and build the "test_convert" binary. + + + Set some non-ascii locale in the environment. On Linux, one can + run, for example: +$ export LC_CTYPE=ru_RU.KOI8-R + + + + + Run the "test_convert" binary with any non-ascii string in the + selected encoding as its parameter. If you see a list of Unicode codepoints, + everything's OK. Otherwise, locale support on your system might be + broken. + + + + +
+ +
+ Allowing Unknown Options + + Usually, the library throws an exception on unknown option names. This + behaviour can be changed. For example, only some part of your application uses + Program_options, and you wish to pass unrecognized options to another part of + the program, or even to another application. + + 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 allow_unregistered + method of that class: + +parsed_options parsed = + command_line_parser(argc, argv).options(desc).allow_unregistered().run(); + + + 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 string_key and value fields of the instance will contain results + of syntactic parsing of the token, the unregistered field will be set to true, + and the original_tokens field will contain the token as it appeared on the command line. + + + If you want to pass the unrecognized options further, the + collect_unrecognized 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: + +vector<string> to_pass_further = collect_unrecognized(parsed.options, include_positional); + + + + +
+ +
+ Testing Option Presence + + Until now we have tested whether an option has been set using the + count 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: + (), "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() << ".\n"; +} else { + cout << "Compression level was not set.\n"; +} +]]> + + + + Instead, you can use a variable of type boost::optional; + Program_options provides special support for Boost.Optional + such that if the user specifies the option the boost::optional + variable will be initialized to the appropriate value: + 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"; +} +]]> + + +
+ +
+ + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/index.html b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/index.html new file mode 100644 index 00000000..83b096e2 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/index.html @@ -0,0 +1,14 @@ + + + + + +Automatic redirection failed, please go to +../../../doc/html/program_options.html + 
+

© Copyright Beman Dawes, 2001

+

Distributed under the Boost Software License, Version 1.0. (See accompanying +file LICENSE_1_0.txt or copy +at www.boost.org/LICENSE_1_0.txt)

+ + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/overview.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/overview.xml new file mode 100644 index 00000000..52fe9b98 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/overview.xml @@ -0,0 +1,695 @@ + + + %entities; +]> +
+ Library Overview + + In the tutorial section, we saw several examples of library usage. + Here we will describe the overall library design including the primary + components and their function. + + + The library has three main components: + + + The options description component, which describes the allowed options + and what to do with the values of the options. + + + + The parsers component, which uses this information to find option names + and values in the input sources and return them. + + + + The storage component, which provides the + interface to access the value of an option. It also converts the string + representation of values that parsers return into desired C++ types. + + + + + + To be a little more concrete, the options_description + class is from the options description component, the + parse_command_line function is from the parsers component, and the + variables_map class is from the storage component. + + In the tutorial we've learned how those components can be used by the + main function to parse the command line and config + file. Before going into the details of each component, a few notes about + the world outside of main. + + + + For that outside world, the storage component is the most important. It + provides a class which stores all option values and that class can be + freely passed around your program to modules which need access to the + options. All the other components can be used only in the place where + the actual parsing is the done. However, it might also make sense for the + individual program modules to describe their options and pass them to the + main module, which will merge all options. Of course, this is only + important when the number of options is large and declaring them in one + place becomes troublesome. + + + + +
+ Options Description Component + + The options description component has three main classes: + &option_description;, &value_semantic; and &options_description;. The + first two together describe a single option. The &option_description; + class contains the option's name, description and a pointer to &value_semantic;, + which, in turn, knows the type of the option's value and can parse the value, + apply the default value, and so on. The &options_description; class is a + container for instances of &option_description;. + + + For almost every library, those classes could be created in a + conventional way: that is, you'd create new options using constructors and + then call the add method of &options_description;. However, + that's overly verbose for declaring 20 or 30 options. This concern led + to creation of the syntax that you've already seen: + +options_description desc; +desc.add_options() + ("help", "produce help") + ("optimization", value<int>()->default_value(10), "optimization level") + ; + + + + The call to the value function creates an instance of + a class derived from the value_semantic class: typed_value. + That class contains the code to parse + values of a specific type, and contains a number of methods which can be + called by the user to specify additional information. (This + essentially emulates named parameters of the constructor.) Calls to + operator() on the object returned by add_options + forward arguments to the constructor of the option_description + class and add the new instance. + + + + Note that in addition to the + value, library provides the bool_switch + function, and user can write his own function which will return + other subclasses of value_semantic with + different behaviour. For the remainder of this section, we'll talk only + about the value function. + + + The information about an option is divided into syntactic and + semantic. Syntactic information includes the name of the option and the + number of tokens which can be used to specify the value. This + information is used by parsers to group tokens into (name, value) pairs, + where value is just a vector of strings + (std::vector<std::string>). The semantic layer + is responsible for converting the value of the option into more usable C++ + types. + + + This separation is an important part of library design. The parsers + use only the syntactic layer, which takes away some of the freedom to + use overly complex structures. For example, it's not easy to parse + syntax like: calc --expression=1 + 2/3 because it's not + possible to parse 1 + 2/3 without knowing that it's a C + expression. With a little help from the user the task becomes trivial, + and the syntax clear: calc --expression="1 + 2/3" + + +
+ Syntactic Information + The syntactic information is provided by the + boost::program_options::options_description class + and some methods of the + boost::program_options::value_semantic class + and includes: + + + + name of the option, used to identify the option inside the + program, + + + + + description of the option, which can be presented to the user, + + + + + the allowed number of source tokens that comprise options's + value, which is used during parsing. + + + + + + Consider the following example: + +options_description desc; +desc.add_options() + ("help", "produce help message") + ("compression", value<string>(), "compression level") + ("verbose", value<string>()->implicit_value("0"), "verbosity level") + ("email", value<string>()->multitoken(), "email to send to") + ; + + 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: + + test --help --compression 10 --verbose --email beadle@mars beadle2@mars + + + +
+ Description formatting + + + 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. + + + 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). + + + You may specify additional indent for the first specified by + inserting spaces at the beginning of a paragraph. For example: + +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 ") + ; + + will specify a four-space indent for the first line. The output will + look like: + + --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 + + + + + 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: + +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"); + + will produce: + + --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 + + 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. + + +
+ +
+ +
+ Semantic Information + + The semantic information is completely provided by the + boost::program_options::value_semantic class. For + example: + +options_description desc; +desc.add_options() + ("compression", value<int>()->default_value(10), "compression level") + ("email", value< vector<string> >() + ->composing()->notifier(&your_function), "email") + ; + + 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 &your_function, passing the value of the + "email" option as argument. + +
+ +
+ Positional Options + + 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 positional option, + which does not specify any name at all, for example: + + archiver --compression=9 /etc/passwd + + Here, the "/etc/passwd" element does not have any option name. + + + 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 + options, so that the above command line can be interpreted the same way + as: + + archiver --compression=9 --input-file=/etc/passwd + + + + 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: + +positional_options_description pd; pd.add("input-file", 1); + specifies that for exactly one, first, positional + option the name will be "input-file". + + + It's possible to specify that a number, or even all positional options, be + given the same name. + +positional_options_description pd; +pd.add("output-file", 2).add("input-file", -1); + + In the above example, the first two positional options will be associated + with name "output-file", and any others with the name "input-file". + + + + 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. + + + +
+ + + +
+ +
+ Parsers Component + + The parsers component splits input sources into (name, value) pairs. + Each parser looks for possible options and consults the options + description component to determine if the option is known and how its value + is specified. In the simplest case, the name is explicitly specified, + which allows the library to decide if such option is known. If it is known, the + &value_semantic; instance determines how the value is specified. (If + it is not known, an exception is thrown.) Common + cases are when the value is explicitly specified by the user, and when + the value cannot be specified by the user, but the presence of the + option implies some value (for example, true). So, the + parser checks that the value is specified when needed and not specified + when not needed, and returns new (name, value) pair. + + + + To invoke a parser you typically call a function, passing the options + description and command line or config file or something else. + 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. + + + + There are three exceptions to the above model -- all related to + traditional usage of the command line. While they require some support + from the options description component, the additional complexity is + tolerable. + + + The name specified on the command line may be + different from the option name -- it's common to provide a "short option + name" alias to a longer name. It's also common to allow an abbreviated name + to be specified on the command line. + + + + Sometimes it's desirable to specify value as several + tokens. For example, an option "--email-recipient" may be followed + by several emails, each as a separate command line token. This + behaviour is supported, though it can lead to parsing ambiguities + and is not enabled by default. + + + + The command line may contain positional options -- elements + which don't have any name. The command line parser provides a + mechanism to guess names for such options, as we've seen in the + tutorial. + + + + + +
+ + +
+ Storage Component + + The storage component is responsible for: + + + Storing the final values of an option into a special class and in + regular variables + + + Handling priorities among different sources. + + + + Calling user-specified notify functions with the final + values of options. + + + + + Let's consider an example: + +variables_map vm; +store(parse_command_line(argc, argv, desc), vm); +store(parse_config_file("example.cfg", desc), vm); +notify(vm); + + The variables_map class is used to store the option + values. The two calls to the store function add values + found on the command line and in the config file. Finally the call to + the notify function runs the user-specified notify + functions and stores the values into regular variables, if needed. + + + The priority is handled in a simple way: the store + function will not change the value of an option if it's already + assigned. In this case, if the command line specifies the value for an + option, any value in the config file is ignored. + + + + Don't forget to call the notify function after you've + stored all parsed values. + + +
+ +
+ Specific parsers + +
+ Configuration file parser + + The &parse_config_file; function implements parsing + of simple INI-like configuration files. Configuration file + syntax is line based: + + + A line in the form: + +name=value + + gives a value to an option. + + A line in the form: + +[section name] + + introduces a new section in the configuration file. + + The # character introduces a + comment that spans until the end of the line. + + + + The option names are relative to the section names, so + the following configuration file part: + +[gui.accessibility] +visual_bell=yes + + is equivalent to + +gui.accessibility.visual_bell=yes + + When the option "gui.accessibility.visual_bell" has been added to the options + +options_description desc; +desc.add_options() + ("gui.accessibility.visual_bell", value<string>(), "flash screen for bell") + ; + +
+ +
+ Environment variables parser + + Environment variables are string variables + which are available to all programs via the getenv 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 + autoexec.bat file or (on recent versions) the + Control Panel/System/Advanced/Environment Variables + dialog, and on Unix —, the /etc/profile, + ~/.profile and ~/.bash_profile + files. Because environment variables can be set for the entire system, + they are particularly suitable for options which apply to all programs. + + + 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. + + 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 proxy the environment variable might be called + BOOST_PROXY. 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 BOOST_ as the prefix, and there are + two variables, CVSROOT and BOOST_PROXY, the + first variable will be ignored, and the second one will be converted to + option proxy. + + + 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 std::string and returning + std::string. 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". + + +
+
+ +
+ Types + + 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. + + 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. + + Booleans a special in that there are multiple ways to come at them. + Similar to another value type, it can be specified as ("my-option", + value<bool>()), and then set as: + +example --my-option=true + + However, more typical is that boolean values are set by the simple + presence of a switch. This is enabled by &bool_switch; as in + ("other-option", bool_switch()). This will cause the value to + default to false and it will become true if the switch is found: + +example --other-switch + + 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. +
+ +
+ Annotated List of Symbols + + The following table describes all the important symbols in the + library, for quick access. + + + + + + + + + + Symbol + Description + + + + + + + Options description component + + + + &options_description; + describes a number of options + + + &value; + defines the option's value + + + + Parsers component + + + + &parse_command_line; + parses command line (simpified interface) + + + + &basic_command_line_parser; + parses command line (extended interface) + + + + + &parse_config_file; + parses config file + + + + &parse_environment; + parses environment + + + + Storage component + + + + &variables_map; + storage for option values + + + + + + + +
+ +
+ + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/post_review_plan.txt b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/post_review_plan.txt new file mode 100644 index 00000000..38a22ec2 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/post_review_plan.txt @@ -0,0 +1,181 @@ + + Program options post-review development plan. + +0. Convert all documentation to BoostBook format + +1. (done) + Simplify and clarify interface. + + It turns out that most users are interested in 'variables_map' class, so + it must be possible to use it directly, without even knowing about + 'options_and_arguments'. The proposed interface is: + + options_description desc; + .... + variables_map vm; + load_from_command_line(vm, desc, argc, argv); + +2. (done) + Better separation of syntaxic and semantic processing, as suggested by + Pavol Droba. + + The problem with current 'option_description' interface is that the + 'validator' and 'notifier' callbacks are not really usable by ordinary + users --- it's extender's interface. The current 'parameter' function uses + those callback to provide user-friendly semantic interface, but it's not + documented nor completely worked out. + + In the new interface, the second parameter of 'option_description' ctor + will have two possibilities: just a string and a pointer to a new class + 'value_descriptor'. When passed the latter, it will invoke the instance on + itself, and then delete the object. A function 'value' will be provided, + that will create value specific for a type. + + Example + ("magic", value("n", &n)->default_value(10), "magic value"). + + The 'value' function will create instances of 'typed_value_descriptor' + type, with the following methods: + - default_value + - interpreter + - validator + - notifier + + The 'option_description' class we'll have two attributes to support + semantic operation: 'generator', which will handle conversion from string + into value (including application of default value), and 'notifier'. Similiar + to the the current design, those attributes will be set by + 'value_descriptor' instances. + + Another function, "bool_switch" will create value descriptor for type bool, + with default value of false. The function is needed to avoid special-casing + 'value' function on bool type, which was considered confusing (Neal D. Becker). + +3. (done) Support for positional options. + + Positional options will be treated uniformly with ordinary ones. User will + be able to specify that, for example, third positional option is to be + interpreted as option "output-file" with the same value. + + The user interface will be simple: user will provide two instanes of + 'options_description' to functions which parse command line. For example. + + options_description desc; + desc.add_options() + ("magic", "n", "magic value") + ; + + options_description pdesc; + pdesc.add_options() + ("output-file", "n", "output file") + ("input-files*", value< vector >("n"), "files") + ; + + variables_map vm; + load_from_command_line(vm, desc, pdesc, argc, argv); + +4. (done, except for registry) + Multiple sources improvement. + + Need to implement support for registry/environment. + Also, must devise a way to handle different naming of option in + sources. Lastly, the storing of values into program variables should + become part of 'variables_map' interface. + +5. Improve documentation. + + Chuck Messenger: + "When code is given for an example program, after the code, give examples of + using the program, along with the expected output." + + Pavol Droba: + "I would prefer a few chapters explaining various components of the + library, each followed by a reference." + + Pavel Vozenilek: + > Documentation should contain list of compilers the library works on and + > also info whether MSVC 6 port is feasible or not. + > + > The non-Doxygen part of documentation can be also a bit expanded: e.g. I + > would welcome some high level overview of the algorithms and structures and + > info about expected CPU/memory consumption. + > + > Also info whether there are any internal limits (like option length) . + > + > Some examples may be bit more annotated, also contain what is expected + > output. + + Syntax highligting. + + Document "*" in option names + Automated tests for examples? + (new) Comments inside code snippets? + (new) Table of all symbols + + +6. (deferred) + Unicode support + + - unicode in argv/argc + - Unicode in config files not supported + ( + The difference between ASCII and unicode files is: + - big endian UTF16 starts with 2 bytes FE FF 9mandatory by Unicode + standard) - little endian UTF16 starts with FF FE + - UTF8 text starts with EF BB BF + + Pavel Vozenilek + ) + +7. Config file improvements + + - should have "allow_unregistered" for config_file. + - (done) bool options in config file do not work. + - "#" inside strings, in config files (Pavel Vozenilek) + +8. + Cmdline improvements + + - must be able to parse WinMain string + - support for response files + +9. Other changes. + + - (outdated) get_value -> value (Beman) + - (done) is "argv" const in std, or not? Adjust docs if not. + - variables_map::count_if, find_if (Tanton Gibbs) + - Works with exceptions disabled. + - (outdated) disallow empty name for the 'parameter' function + - check for prefixes if 'allow_guessing' is on + - check for duplicate declaration of options. + - test additional parser + - Show default values in help output + - Adaptive field width + - 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 + - (new) variables_map should throw when value not found + - (important) decide where we check that the number of passed option + tokens is less than the allowed number. In parser or later? + - (important) what if the same option has different definitions? + - (new) We lost the ability to specify options_description instance + in call to 'store'. So now we can't store just subset of options. + Is it a problem? + - (new) Improve formatting of 'arg'. + - (new) revive real and regexp examples. + - (new) even more simpler syntax for assignent to var? + + +10. Uncertain + - Function to get program name + - Order of 'description' and 'value'. + + +11. (new) Look at all "TODO" comments. + (new) Check that all methods are documented. + + +12. Deferred + + - setting a flag when option is found diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.dox b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.dox new file mode 100644 index 00000000..1e1e423e --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.dox @@ -0,0 +1,162 @@ +/** @mainpage Program options documentation + + @section scope Scope + + Briefly, the library should allow program developers to obtain + program options, i.e. (name,value) pairs from the user, + via conventional methods such as command line and config file. + + Necessary facilities include: + - parse command line + - parse config files + - perform semantic validation on input, such as checking for correct + type of parameters, and storing values. + - combine all inputs together, so that all program options can + be obtained in one place. + + @section goals Goals + The fundamental goals for this library were: + - it should be more convenient to use it than parse command line by hand, + even when the number of possible options is 2, + - all popular command line styles should be supported, + - "you pay for what you use" principle is important: simple utilities + need not be forced to depend on excessive amount of code. + - it must be possible to validate option values, convert them to required + types, and store either in program variables, or in data structures + maintained by the library. + - data from command line and config file should be usable together, and + alternative program option sources (such as registry) should be + possible. + + @section design_overview Design overview + + To meet the stated goals, the library uses a layered architecture. + -# At the bottom, there are two parser classes, + boost::program_options::cmdline and + boost::program_options::config_file. + They are responsible for syntax matters only and provide simple + iterator-like interface. + -# The boost::program_options::options_and_arguments holds the result of parsing command line or + config file. It is still concerned with syntax only and holds precisely + what is found on command line. There's a couple of associated parse + functions ( + @ref parse_cmdline_func "1", + @ref parse_config_file_func "2"), + which relieve the user from the need to iterate over options + and arguments manually. + -# The class boost::program_options::options_description is a high-level + description of allowed + program options, which does not depend on concrete parser class. In + addition, it can be used to provide help message. There are parse + functions which return options_and_arguments given options_description. + -# The options_description class also has semantic responsibilities. It's + possible to specify validators for option, their default values, and the + like. There's a function boost::program_options::perform_semantic_actions, + which handles this information and returns a map of option values. + -# Finally, at the top, there boost::program_options::variables_map class. + It's possible to + store options in it, and obtain them later. Another feature is that + different variable_map instances can be linked together, so that both + command line and config file data is used. Additional option sources can + be added at this level. + + @section futher_reading Futher reading + + To get further information about the library, you might want to read + the documentation for the classes referenced above. Another possibility + is to look through the examples: + + - @ref options_description "simple usage" + - @ref variables_map "parsing with validation and assignment to program variables" + - @ref multiple_sources "using command line and config file together" + - @ref custom_syntax "customized options syntax" + - @ref real_example "real example" + - @ref custom_validator "custom validator" + - @ref multiple_modules "possible approach for multi-module programs" + - @ref cmdline "low level cmdline parsing" + + Finally, you might want the check out the @ref recipes "recipes" page. +*/ + +/** @page examples Examples + + - @ref options_description "simple usage" + - @ref variables_map "parsing with validation and assignment to program variables" + - @ref multiple_sources "using command line and config file together" + - @ref custom_syntax "customized options syntax" + - @ref real_example "real example" + - @ref custom_validator "custom validator" + - @ref multiple_modules "possible approach for multi-module programs" + - @ref cmdline "low level cmdline parsing" +*/ + +/** @page options_description Options description + + Example of quite a simple usage. Options are registered and the + command line is parsed. The user is responsible to interpreting the + option values. This also how automatic help message. + + @include options_description.cpp +*/ + +/** @page variables_map Variables map + + In this example, the parameter function is used to enable + validation of options (i.e. checking that they are of correct type). + The option values are also stored in program variables. + + @include variables_map.cpp +*/ + +/** @page multiple_sources Multiple sources + + It is possible for program options to come from different sources. + Here, the command line and a config file are used, and the values + specified in both are combined, with preferrence given to the + command line. + + @include multiple_sources.cpp +*/ + +/** @page custom_syntax Custom syntax + + Some applications use a custom syntax for the command line. In this + example, the gcc style of "-fbar"/"-f" is handled. + + @include custom_syntax.cpp +*/ + +/** @page real_example A real example + + Shows how to use custom option description class and custom formatter. + Also validates some option relationship. + + @include real.cpp +*/ + +/** @page multiple_modules Multiple modules + + Large programs are likely to have several modules which want to use + some options. One possible approach is show here. + @sa @ref recipe_multiple_modules + + @include multiple_modules.cpp +*/ + +/** @page custom_validator Custom validator + + It's possible to plug in arbitrary function for converting the string + value from the command line to the value used in your program. The + example below illustrates this. + + @include regex.cpp +*/ + +/** @page cmdline The cmdline class + + When validation or automatic help message are not needed, it's possible + to use low-level boost::program_options::cmdline class, like shown + in this example. + + @include cmdline.cpp +*/ \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.ent b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.ent new file mode 100644 index 00000000..cd6504b8 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.ent @@ -0,0 +1,48 @@ + +positional_options_description"> + +options_description"> + +option_description"> + +value_semantic"> + +parsed_options"> + +variables_map"> + + +value"> + +parse_command_line"> + +parse_config_file"> + +parse_environment"> + +store"> + +command_line_parser"> + +basic_command_line_parser"> + + +basic_option"> + +bool_switch"> diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.xml b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.xml new file mode 100644 index 00000000..cd879f7d --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/program_options.xml @@ -0,0 +1,87 @@ + + + + + + Vladimir + Prus + + + + 2002 + 2003 + 2004 + Vladimir Prus + + + + 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) + + + + + + Facilities to obtain configuration data from command line, config files + and other sources + + + + Boost.Program_options + +
+ Introduction + + 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. + + Why would you use such a library, and why is it better than parsing + your command line by straightforward hand-written code? + + + It's easier. The syntax for declaring options is simple, and + the library itself is small. Things like conversion of option values to + desired type and storing into program variables are handled + automatically. + + + + Error reporting is better. All the problems with the command line are + reported, while hand-written code can just misparse the input. In + addition, the usage message can be automatically generated, to + avoid falling out of sync with the real list of options. + + + Options can be read from anywhere. Sooner or later the command + line will be not enough for your users, and you'll want config files + or maybe even environment variables. These can be added without significant + effort on your part. + + + + + + + Now let's see some examples of the library usage in the . + + +
+ + + + + + + + + + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/questions b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/questions new file mode 100644 index 00000000..f0f055f9 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/questions @@ -0,0 +1,16 @@ + +Rename 'parameter' in option_description with something +better, e.g. 'value_specification'? + +Approximate matching for variable_map access? + +Should be able to stack validators? + +Case with variables like this + 'foo' = 10 + 'foo.bar' = 12 + should become an error + + + + diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/questions.dox b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/questions.dox new file mode 100644 index 00000000..2cd81945 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/questions.dox @@ -0,0 +1,12 @@ +/** @page open_questions Open questions. + +
    +
  1. Shouldn't validators always use "C" locale? + +
  2. Shouldn't validator for intr check for different bases? + +
  3. Does anyone need "getop_option_description"?. + +
+ +*/ \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/rationale b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/rationale new file mode 100644 index 00000000..03192a91 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/rationale @@ -0,0 +1,15 @@ + +We could either implement simple chaining for variable maps, or +implement generic composition classes. The former was choosen, +mostly because of simplicity. + +There were two implementation approaches for multiple option +occurrences in options_and_arguments. First is store them +separately. The advantage is that it's easy to obtain all +occurrences before certain position on command line. The +disadvantage is that we cannot return a reference to +vector > 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 occurrences of +a single option that were before some point. That's possible +with vector > storage. diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/rationale.dox b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/rationale.dox new file mode 100644 index 00000000..388bba2f --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/rationale.dox @@ -0,0 +1,95 @@ +/** @page rationale Rationale + + @section code_size Focus on code size + + The program options library has two important properties: + - runtime performance is not important. After all, command line processing + is done only once, and the amount of data is small. + - code size matters. Since parsing command line is utility task, users + won't be glad to have lots of code linked to every binary which has + options. + + For the above reasons, the the library is designed so that it can be easily + used as shared library, with minimum code on the side of main application. + In particular, templates are used only where necessary, for example for + validation of user-defined types. In other places, boost::function is + used to allow customization, but keep templates out of the public + interface. + + @section string_vs_enums Strings vs. enums + + In some places, the library uses strings to convey information that + could be represented by enumerations or values. For example, + the program_options::option_description class allows to add "?" to the + parameter name to specify that the parameter is optional. For another + example, while program_options::cmdline class allows to obtain the + index of option, it does not require to specify an index for each option, + and it's possible to tell options by their names. + + Such interface appears to be much more usable. If we were using + enumeration for different properties of parameter, there would be + another argument to many functions, the need to type long, possible + qualified names, and little advantage. + + That little advantage is that if you type a wrong enumeration name, + you'd get a compile error. If you type '!' instead of '?' after parameter + name, you'd get incorrect behaviour. However, such errors are deemed + rare. + + @section char_vs_string const char* vs. std::string + + Most of the interface uses const char* where std::string seems a natural + choice. The reason is that those functions are called many times: for + example to declare all options. They are typically called with string + literals, and implicit conversion to string appears to take a lot of + code space. Providing both std::string and const char* version would + considerably bloat the interface. Since passing std::string is considered + rare, only const char* versions are provided. + + @section init_syntax Initialization syntax + + The syntax used for creating options_description instance was designed to + be as easy as possible in the most common case. Consider: + @code + desc.add_options() + ("verbose", "", "verbosity level") + ("magic", "int", "magic value").notify(some_func) + ; + @endcode + Here, most common properties of options: name, presense of parameter and + description, are specified very concisely, and additional properties can + be given quite naturally, too. + + Another possibility would be: + @code + option_description d1(...), d2(...); + desc.add(d1 & d2); + @endcode + or + @code + option_description d1(...), d2(...); + desc = d1, d2; + @endcode + + The drawback is the need to explicitly create new objects and give names + to them. The latter problem can be helped if objects are created inside + expressions: + @code + desc = option_description(...), option_description(...) + @endcode + but there's still extra typing. + + @section help_handling Handling of --help + + It was suggested by Gennadiy Rozental that occurrence of --help + on command line results in throwing an exception. Actually, the + "special" option must have been configurable. This was not + implemented, because applications might reasonable want to process + the rest of command line even of --help was seen. For example, + --verbose option can control how much help should be output, + or there may be several subcommand with different help screens. + + + + +*/ \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/recipes.dox b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/recipes.dox new file mode 100644 index 00000000..a3cd623e --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/recipes.dox @@ -0,0 +1,91 @@ +/** @page recipes Recipes + + Here, we'll give solution for some desires which seem common. + + @section recipe_parameter_validation How to check for correct option value types and assign them? + + There's the boost::program_options::parameter function. It + returns a object, which, if passed as the second parameter + to boost::program_options::option_description constructor, + establishes correct validation routine. A simple example + is + @code + options_description desc; + desc.add_options() + ("foo", parameter("arg"), "obscure option") + ; + @endcode + + If you pass an address of int variable as the second + parameter of the parameter function, that variable will + be assigned the options's value. + + @sa @ref variables_map + + @section recipe_lazy What if I don't want to declare any options? + + I'm not sure this is good idea. In particular, mistyped options + will be silently ignored, leading to possible user surprises. + Futher, the boost::program_options::cmdline class was specially + designed to be very lightweight. + + Anyway, there's a version of the parse_command_line function + which does not take an options_description instance. Also, the + cmdline class ctor accepts an 'allow_unregistered' parameter. + In both cases, all options will be allowed, and treated as if + they have optional parameter. + + Note that with the default style, + @verbatim + --foo bar + @endverbatim + will be taken as option "foo" with value "bar", which is + probably not correct. You should disable option parameter in + the next token to avoid problems. + + @sa boost::program_options::cmdline + + @section recipe_multiple_modules I have several separate modules which must controlled by options. What am I to do? + + There are several solutions. + + @subsection sb1 Everything's global + + You can create a single instance of the options_description class + somewhere near main. All the modules will export their own + options using other options_description instances which can + be added to the main one. After that, you'd parse command line and + config files. The parsing results will be stored in one variables_map, + which will be passed to all modules, which can work with their own + options. + + @subsection sb2 Private option data + + Assume one of the modules does not like to see irrelevant options. + For example, it outputs a configuration file for other program, and + irrelevant options will confuse that program. + + It's possible to give the module only the options that it has + registered. First, the module provides an options_description instance + which is added to the global one. Second the command line is parsed + to produce an options_and_arguments instance. Lastly, the store + function is called. If passed the options_description instance previously + returned by the module, it will store only options specified in that + instance. + @sa @ref multiple_modules + + + @subsection sb3 Unique option names + + The most general solution would be to give unique names to options + for different modules. One module will declare option "module1.server", + and another would declare "module2.internal_checks". Of course, there + can be global options like "verbosity", declared by main and + used by all modules. + + This solution avoids all possible name clashes between modules. On + the other hand, longer option names can be less user-friendly. This + problem can be alleviated if module prefix is used only for less + common option, needed for fine-tuning. + +*/ \ No newline at end of file diff --git a/3rd_party_lib/boost_1_72_0/libs/program_options/doc/requirements-Rozental b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/requirements-Rozental new file mode 100644 index 00000000..580fb9c5 --- /dev/null +++ b/3rd_party_lib/boost_1_72_0/libs/program_options/doc/requirements-Rozental @@ -0,0 +1,209 @@ +From rogeeff@mail.com Fri Nov 16 19:57:49 2001 +Received: from imap.cs.msu.su (imap.cs.msu.su [158.250.10.15]) + by redsun.cs.msu.su (8.9.3/8.9.3) with ESMTP id TAA06515 + for ; Fri, 16 Nov 2001 19:59:43 +0300 (MSK) +Received: from n15.groups.yahoo.com (n15.groups.yahoo.com [216.115.96.65]) + by imap.cs.msu.su (8.11.6/8.11.6) with SMTP id fAGGtrd57869 + for ; Fri, 16 Nov 2001 19:55:54 +0300 (MSK) + (envelope-from sentto-1234907-17382-1005929874-ghost=cs.msu.su@returns.groups.yahoo.com) +X-eGroups-Return: sentto-1234907-17382-1005929874-ghost=cs.msu.su@returns.groups.yahoo.com +Received: from [10.1.1.222] by n15.groups.yahoo.com with NNFMP; 16 Nov 2001 16:57:42 -0000 +X-Sender: rogeeff@mail.com +X-Apparently-To: boost@yahoogroups.com +Received: (EGP: mail-8_0_0_1); 16 Nov 2001 16:57:53 -0000 +Received: (qmail 2553 invoked from network); 16 Nov 2001 16:57:53 -0000 +Received: from unknown (216.115.97.172) + by m4.grp.snv.yahoo.com with QMQP; 16 Nov 2001 16:57:53 -0000 +Received: from unknown (HELO n6.groups.yahoo.com) (216.115.96.56) + by mta2.grp.snv.yahoo.com with SMTP; 16 Nov 2001 16:57:53 -0000 +X-eGroups-Return: rogeeff@mail.com +Received: from [10.1.10.109] by n6.groups.yahoo.com with NNFMP; 16 Nov 2001 16:57:52 -0000 +To: boost@yahoogroups.com +Message-ID: <9t3gid+hdf3@eGroups.com> +In-Reply-To: +User-Agent: eGroups-EW/0.82 +X-Mailer: eGroups Message Poster +X-Originating-IP: 199.119.33.162 +From: "Gennadiy E. Rozental" +X-Yahoo-Profile: rogeeff +MIME-Version: 1.0 +Mailing-List: list boost@yahoogroups.com; contact boost-owner@yahoogroups.com +Delivered-To: mailing list boost@yahoogroups.com +Precedence: bulk +List-Unsubscribe: +Date: Fri, 16 Nov 2001 16:57:49 -0000 +Reply-To: boost@yahoogroups.com +Subject: [boost] Re: arguments parsing, wildcard matcher +Content-Transfer-Encoding: 7bit +Content-Type: text/plain; + charset=US-ASCII +Content-Length: 5662 +Status: R +X-Status: N + +--- In boost@y..., Vladimir Prus wrote: +> +> > Just a couple of classes I wrote that I wondered if anyone thought +> > any place in boost: +> > +> > arguments : simple command-line arguments and options parser: +> > +> > class arguments +> > { +> > public: +> > arguments(int argc, char* argv[]); +> > +> > bool has_option(const char* name) const; +> > bool get_option(const char* name, bool& value) const; +> +> > Any interest? Already proposed? Wasting my time? +> +> Actually, I'm already working on library with the same goals but +more +> elaborated. Moreover, it's almost finished. I planned to announce +it later, +> but have to do it now. My design goals were: +> - It should be resonable to use the library to parse as little as +2 command +> line options. +> - It must be extandable to privide any resonable handling +> - since command line is just a way to affect the program behaviour, +other +> ways to accomplish that must be provided, most notable is +configuration file +> - library should provide a way to store information from command +line and +> config file in a way allowing easy retrieval and using to change +configurable +> parameters of the program. +> +> The docs are available at: +> http://chronos.cs.msu.su/~ghost/projects/config_db/doc/index.html +> +> Let me know what you think. + +Privet, Volodya. + +Here what I am looking for to be supported by Command Line Argument +Framework directly or by means of easy extension: + +1. command line argument formats + a. - + b. - + c. - + d. -