senf/Utils/Console/ProgramOptions.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief ProgramOptions public header */
  30
  31 #ifndef HH_SENF_Scheduler_Console_ProgramOptions_
  32 #define HH_SENF_Scheduler_Console_ProgramOptions_ 1
  33
  34 // Custom includes
  35 #include "Config.hh"
  36
  37
  38 //#include "ProgramOptions.mpp"
  39 #include "ProgramOptions.ih"
  40 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  41
  42 namespace senf {
  43 namespace console {
  44
  45     /** \brief Console node tree based command line option parser
  46
  47         A ProgramOptions instance allows flexible parsing of command line options against the
  48         console node tree. If you just want to parse all options, the senf::console::parseOptions()
  49         function will do that. ProgramOptions however allows to incrementally parse only a
  50         subset of the given command line options.
  51         \code
  52         std::vector<std::string> args;
  53         senf::console::ProgramOptions cf (argc, argv);
  54         cf
  55             .nonOptions(args)
  56             .alias('n', "--foo-bar=x")
  57             .alias('x', "--xxx", true);
  58
  59         // Parse only options under the directory of some object. The object 'ob'
  60         // must have been registered somewhere in the node tree
  61         cf.parse(ob.dir);
  62
  63         // Parse rest of the config file
  64         cf.parse();
  65         \endcode
  66
  67         If your application uses multiple configuration sources, use a ConfigBundle and
  68         OptionsConfig.
  69
  70         \ingroup console_access
  71       */
  72     class ProgramOptions
  73         : public detail::BundleMixin
  74     {
  75     public:
  76         //-////////////////////////////////////////////////////////////////////////
  77         ///\name Structors and default members
  78         //\{
  79
  80         ProgramOptions(int argc, char const ** argv, DirectoryNode & root = root());
  81                                         ///< Create ProgramOptions parser for given options
  82                                         /**< The given argc/argv values are those passed to main by
  83                                              the operating system. Especially argv[0] is \e not an
  84                                              option and is ignored. */
  85
  86         //\}
  87         //-////////////////////////////////////////////////////////////////////////
  88
  89         template <class Container>
  90         ProgramOptions & nonOptions(Container & container);
  91                                         ///< Set container to add non-option arguments to
  92                                         /**< \a container must have a \c clear() and a \c
  93                                              push_back(std::string) member. All non-options are
  94                                              added to \a container. Before parsing the command-line,
  95                                              \a clear() is called. */
  96         ProgramOptions & alias(char letter, std::string const & longOpt, bool withArg=false);
  97                                         ///< Set short option alias
  98                                         /**< A short option is always an alias for a long option
  99                                              with or without argument. if \a withArg is \c true, the
 100                                              short option will expect an argument on the command
 101                                              line. This argument will be appended (with an
 102                                              additional '=') to \a longOpt. If \a withArg is \c
 103                                              false (the default), \a longOpt may optional contain an
 104                                              argument.
 105                                              \param[in] letter option letter
 106                                              \param[in] longOpt long option alias
 107                                              \param[in] withArg \c true, if the option should take
 108                                                  an argument. */
 109
 110     private:
 111         detail::ProgramOptionsSource & config_;
 112     };
 113
 114     /** \brief Parse command line options
 115
 116         The command line options in \a argc / \a argv will be parsed, interpreting all node's
 117         relative to \a root as root node.
 118
 119         \related ProgramOptions
 120      */
 121     void parseOptions(int argc, char const ** argv, DirectoryNode & root = root());
 122
 123     /** \brief ConfigBundle source reading command line options
 124
 125         This constructor is used to create a config source parsing the given command line options to
 126         add to a ConfigBundle.
 127
 128         \related ProgramOptions
 129      */
 130     detail::ProgramOptionsSource::ptr OptionsConfig(int argc, char const ** argv);
 131 }}
 132
 133 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 134 #include "ProgramOptions.cci"
 135 //#include "ProgramOptions.ct"
 136 #include "ProgramOptions.cti"
 137 #endif
 138
 139 \f
 140 // Local Variables:
 141 // mode: c++
 142 // fill-column: 100
 143 // comment-column: 40
 144 // c-file-style: "senf"
 145 // indent-tabs-mode: nil
 146 // ispell-local-dictionary: "american"
 147 // compile-command: "scons -u test"
 148 // End: