senf/Utils/Console/ProgramOptions.hh

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