args_handler.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2005, 2006, 2007, 2008, 2009 Ciaran McCreesh
00005  *
00006  * This file is part of the Paludis package manager. Paludis is free software;
00007  * you can redistribute it and/or modify it under the terms of the GNU General
00008  * Public License version 2, as published by the Free Software Foundation.
00009  *
00010  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00011  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00012  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00013  * details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00017  * Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifndef PALUDIS_GUARD_ARGS_ARGS_HANDLER_HH
00021 #define PALUDIS_GUARD_ARGS_ARGS_HANDLER_HH 1
00022 
00023 #include <paludis/args/args_section.hh>
00024 #include <paludis/args/args_group.hh>
00025 #include <paludis/util/instantiation_policy.hh>
00026 #include <paludis/util/private_implementation_pattern.hh>
00027 #include <paludis/util/options.hh>
00028 #include <paludis/util/sequence.hh>
00029 #include <tr1/memory>
00030 #include <iosfwd>
00031 #include <string>
00032 
00033 /** \file
00034  * Declarations for ArgsHandler.
00035  *
00036  * \ingroup g_args
00037  *
00038  * \section Examples
00039  *
00040  * - None at this time.
00041  */
00042 
00043 namespace paludis
00044 {
00045     namespace args
00046     {
00047 
00048 #include <paludis/args/args_handler-se.hh>
00049 
00050         typedef Options<ArgsHandlerOption> ArgsHandlerOptions;
00051 
00052         /**
00053          * Handles command line arguments.
00054          *
00055          * \ingroup g_args
00056          * \nosubgrouping
00057          */
00058         class PALUDIS_VISIBLE ArgsHandler :
00059             private InstantiationPolicy<ArgsHandler, instantiation_method::NonCopyableTag>,
00060             private PrivateImplementationPattern<ArgsHandler>
00061         {
00062             friend class ArgsSection;
00063             friend std::ostream & operator<< (std::ostream &, const ArgsHandler &);
00064 
00065             protected:
00066                 /**
00067                  * Add a new usage line.
00068                  */
00069                 void add_usage_line(const std::string & l);
00070 
00071                 /**
00072                  * Add a new environment line.
00073                  */
00074                 void add_environment_variable(const std::string & e, const std::string & desc);
00075 
00076                 /**
00077                  * Add a new example.
00078                  */
00079                 void add_example(const std::string & e, const std::string & desc);
00080 
00081                 /**
00082                  * Add a new note.
00083                  */
00084                 void add_note(const std::string &);
00085 
00086                 /**
00087                  * Add a new description.
00088                  */
00089                 void add_description_line(const std::string & l);
00090 
00091                 /**
00092                  * Add an new ArgsSection (called by the ArgsSection constructor).
00093                  */
00094                 void add(ArgsSection * const);
00095 
00096                 /**
00097                  * Dump, for --help output (called by operator<<).
00098                  */
00099                 void dump_to_stream(std::ostream & s) const;
00100 
00101                 /**
00102                  * Called after run(), for convenience. Does nothing.
00103                  */
00104                 virtual void post_run();
00105 
00106             public:
00107                 ///\name Basic operations
00108                 ///\{
00109 
00110                 ArgsHandler();
00111 
00112                 virtual ~ArgsHandler();
00113 
00114                 ///\}
00115 
00116                 ///\name Iterate over our parameters (non - and -- switches and their values)
00117                 ///\{
00118 
00119                 struct ParametersConstIteratorTag;
00120                 typedef WrappedForwardIterator<ParametersConstIteratorTag, const std::string> ParametersConstIterator;
00121 
00122                 ParametersConstIterator begin_parameters() const;
00123 
00124                 ParametersConstIterator end_parameters() const;
00125 
00126                 bool empty() const;
00127 
00128                 ///\}
00129 
00130                 /**
00131                  * Add an ArgsOption instance.
00132                  */
00133                 void add_option(ArgsOption * const, const std::string & long_name,
00134                         const char short_name = '\0');
00135 
00136                 /**
00137                  * Remove an ArgsOption instance.
00138                  */
00139                 void remove_option(const std::string & long_name, const char short_name = '\0');
00140 
00141                 ///\name About our application (for documentation)
00142                 ///\{
00143 
00144                 /**
00145                  * What is our application name?
00146                  */
00147                 virtual std::string app_name() const = 0;
00148 
00149                 /**
00150                  * What is our application's Unix manual section?
00151                  */
00152                 virtual std::string man_section() const
00153                 {
00154                     return "1";
00155                 }
00156 
00157                 /**
00158                  * One line synopsis of what our application is.
00159                  */
00160                 virtual std::string app_synopsis() const = 0;
00161 
00162                 /**
00163                  * Long description of what our application is.
00164                  */
00165                 virtual std::string app_description() const = 0;
00166 
00167                 ///\}
00168 
00169                 ///\name Iterate over our usage lines (for documentation)
00170                 ///\{
00171 
00172                 struct UsageLineConstIteratorTag;
00173                 typedef WrappedForwardIterator<UsageLineConstIteratorTag, const std::string> UsageLineConstIterator;
00174 
00175                 UsageLineConstIterator begin_usage_lines() const;
00176 
00177                 UsageLineConstIterator end_usage_lines() const;
00178 
00179                 ///\}
00180 
00181                 ///\name Iterate over our environment lines (for documentation)
00182                 ///\{
00183 
00184                 struct EnvironmentLineConstIteratorTag;
00185                 typedef WrappedForwardIterator<EnvironmentLineConstIteratorTag, 
00186                         const std::pair<std::string, std::string> > EnvironmentLineConstIterator;
00187 
00188                 EnvironmentLineConstIterator begin_environment_lines() const;
00189 
00190                 EnvironmentLineConstIterator end_environment_lines() const;
00191 
00192                 ///\}
00193 
00194                 ///\name Iterate over our examples (for documentation)
00195                 ///\{
00196 
00197                 struct ExamplesConstIteratorTag;
00198                 typedef WrappedForwardIterator<ExamplesConstIteratorTag,
00199                         const std::pair<std::string, std::string> > ExamplesConstIterator;
00200 
00201                 ExamplesConstIterator begin_examples() const;
00202 
00203                 ExamplesConstIterator end_examples() const;
00204 
00205                 ///\}
00206 
00207                 ///\name Iterate over our sections
00208                 ///\{
00209 
00210                 struct ArgsSectionsConstIteratorTag;
00211                 typedef WrappedForwardIterator<ArgsSectionsConstIteratorTag, const ArgsSection> ArgsSectionsConstIterator;
00212 
00213                 ArgsSectionsConstIterator begin_args_sections() const;
00214                 ArgsSectionsConstIterator end_args_sections() const;
00215 
00216                 /**
00217                  * The 'Options' section.
00218                  *
00219                  * Created if it does not exist.
00220                  */
00221                 ArgsSection * main_options_section() PALUDIS_ATTRIBUTE((warn_unused_result));
00222 
00223                 ///\}
00224 
00225                 ///\name Iterate over our notes
00226                 ///\{
00227 
00228                 struct NotesIteratorTag;
00229                 typedef WrappedForwardIterator<NotesIteratorTag, const std::string > NotesIterator;
00230 
00231                 NotesIterator begin_notes() const;
00232                 NotesIterator end_notes() const;
00233 
00234                 ///\}
00235 
00236                 ///\name Iterate over our extra description lines (for documentation)
00237                 ///\{
00238 
00239                 struct DescriptionLineConstIteratorTag;
00240                 typedef WrappedForwardIterator<DescriptionLineConstIteratorTag, const std::string> DescriptionLineConstIterator;
00241 
00242                 DescriptionLineConstIterator begin_description_lines() const;
00243 
00244                 DescriptionLineConstIterator end_description_lines() const;
00245 
00246                 ///\}
00247 
00248 
00249                 /**
00250                  * Parse command line arguments. The third argument is used to
00251                  * set PALUDIS_CLIENT.  The fourth argument is the name of an
00252                  * environment variable holding arguments which are prepended
00253                  * to the command line arguments. The fifth argument is used as
00254                  * a prefix to export our command line via the environment.
00255                  */
00256                 void run(
00257                         const int argc,
00258                         const char * const * const argv,
00259                         const std::string & client,
00260                         const std::string & env_var,
00261                         const std::string & env_prefix,
00262                         const ArgsHandlerOptions & options = ArgsHandlerOptions());
00263 
00264                 /**
00265                  * Parse command line arguments. The third argument is used to
00266                  * set PALUDIS_CLIENT.  The fourth argument is the name of an
00267                  * environment variable holding arguments which are prepended
00268                  * to the command line arguments. The fifth argument is used as
00269                  * a prefix to export our command line via the environment.
00270                  */
00271                 void run(
00272                         const std::tr1::shared_ptr<const Sequence<std::string> > &,
00273                         const std::string & client,
00274                         const std::string & env_var,
00275                         const std::string & env_prefix,
00276                         const ArgsHandlerOptions & options = ArgsHandlerOptions());
00277         };
00278 
00279         /**
00280          * Output an ArgsHandler to an ostream, for --help output.
00281          *
00282          * \ingroup g_args
00283          */
00284         std::ostream & operator<< (std::ostream &, const ArgsHandler &) PALUDIS_VISIBLE;
00285     }
00286 }
00287 
00288 #endif

Generated on Mon Sep 21 10:36:07 2009 for paludis by  doxygen 1.5.4