program_options/detail/cmdline.hpp

0001 // Copyright Vladimir Prus 2002-2004.
0002 // Distributed under the Boost Software License, Version 1.0.
0003 // (See accompanying file LICENSE_1_0.txt
0004 // or copy at http://www.boost.org/LICENSE_1_0.txt)
0005
0006
0007 #ifndef BOOST_CMDLINE_VP_2003_05_19
0008 #define BOOST_CMDLINE_VP_2003_05_19
0009
0010 #include <boost/program_options/config.hpp>
0011 #include <boost/program_options/errors.hpp>
0012 #include <boost/program_options/cmdline.hpp>
0013 #include <boost/program_options/option.hpp>
0014 #include <boost/program_options/options_description.hpp>
0015 #include <boost/program_options/positional_options.hpp>
0016
0017
0018 #include <boost/detail/workaround.hpp>
0019
0020 #include <boost/function.hpp>
0021
0022 #include <string>
0023 #include <vector>
0024
0025 #if defined(BOOST_MSVC)
0026 #   pragma warning (push)
0027 #   pragma warning (disable:4251) // class 'std::vector<_Ty>' needs to have dll-interface to be used by clients of class 'boost::program_options::positional_options_description'
0028 #endif
0029
0030 namespace boost { namespace program_options { namespace detail {
0031
0032     /** Command line parser class. Main requirements were:
0033         - Powerful enough to support all common uses.
0034         - Simple and easy to learn/use.
0035         - Minimal code size and external dependencies.
0036         - Extensible for custom syntaxes.
0037
0038         First all options are registered. After that, elements of command line
0039         are extracted using operator++.
0040
0041         For each element, user can find
0042         - if it's an option or an argument
0043         - name of the option
0044         - index of the option
0045         - option value(s), if any
0046
0047         Sometimes the registered option name is not equal to the encountered
0048         one, for example, because name abbreviation is supported.  Therefore
0049         two option names can be obtained:
0050         - the registered one
0051         - the one found at the command line
0052
0053         There are lot of style options, which can be used to tune the command
0054         line parsing. In addition, it's possible to install additional parser
0055         which will process custom option styles.
0056
0057         @todo mininal match length for guessing?
0058     */
0059     class BOOST_PROGRAM_OPTIONS_DECL cmdline {
0060     public:
0061
0062         typedef ::boost::program_options::command_line_style::style_t style_t;
0063
0064         typedef function1<std::pair<std::string, std::string>,
0065                           const std::string&>
0066             additional_parser;
0067
0068         typedef function1<std::vector<option>, std::vector<std::string>&>
0069             style_parser;
0070
0071         /** Constructs a command line parser for (argc, argv) pair. Uses
0072             style options passed in 'style', which should be binary or'ed values
0073             of style_t enum. It can also be zero, in which case a "default"
0074             style will be used. If 'allow_unregistered' is true, then allows
0075             unregistered options. They will be assigned index 1 and are
0076             assumed to have optional parameter.
0077         */
0078         cmdline(const std::vector<std::string>& args);
0079
0080         /** @overload */
0081         cmdline(int argc, const char*const * argv);
0082
0083         void style(int style);
0084
0085         /** returns the canonical option prefix associated with the command_line_style
0086          *  In order of precedence:
0087          *      allow_long           : allow_long
0088          *      allow_long_disguise  : allow_long_disguise
0089          *      allow_dash_for_short : allow_short | allow_dash_for_short
0090          *      allow_slash_for_short: allow_short | allow_slash_for_short
0091          *
0092          *      This is mainly used for the diagnostic messages in exceptions
0093         */
0094         int         get_canonical_option_prefix();
0095
0096         void allow_unregistered();
0097
0098         void set_options_description(const options_description& desc);
0099         void set_positional_options(
0100             const positional_options_description& m_positional);
0101
0102         std::vector<option> run();
0103
0104         std::vector<option> parse_long_option(std::vector<std::string>& args);
0105         std::vector<option> parse_short_option(std::vector<std::string>& args);
0106         std::vector<option> parse_dos_option(std::vector<std::string>& args);
0107         std::vector<option> parse_disguised_long_option(
0108             std::vector<std::string>& args);
0109         std::vector<option> parse_terminator(
0110             std::vector<std::string>& args);
0111         std::vector<option> handle_additional_parser(
0112             std::vector<std::string>& args);
0113
0114
0115         /** Set additional parser. This will be called for each token
0116             of command line. If first string in pair is not empty,
0117             then the token is considered matched by this parser,
0118             and the first string will be considered an option name
0119             (which can be long or short), while the second will be
0120             option's parameter (if not empty).
0121             Note that additional parser can match only one token.
0122         */
0123         void set_additional_parser(additional_parser p);
0124
0125         void extra_style_parser(style_parser s);
0126
0127         void check_style(int style) const;
0128
0129         bool is_style_active(style_t style) const;
0130
0131         void init(const std::vector<std::string>& args);
0132
0133         void
0134         finish_option(option& opt,
0135                       std::vector<std::string>& other_tokens,
0136                       const std::vector<style_parser>& style_parsers);
0137
0138         // Copies of input.
0139         std::vector<std::string> m_args;
0140         style_t m_style;
0141         bool m_allow_unregistered;
0142
0143         const options_description* m_desc;
0144         const positional_options_description* m_positional;
0145
0146         additional_parser m_additional_parser;
0147         style_parser m_style_parser;
0148     };
0149
0150     void test_cmdline_detail();
0151
0152 }}}
0153
0154 #if defined(BOOST_MSVC)
0155 #   pragma warning (pop)
0156 #endif
0157
0158 #endif
0159