paludis  Version 2.6.0
args_handler.hh
Go to the documentation of this file.
1 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
2 
3 /*
4  * Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011 Ciaran McCreesh
5  *
6  * This file is part of the Paludis package manager. Paludis is free software;
7  * you can redistribute it and/or modify it under the terms of the GNU General
8  * Public License version 2, as published by the Free Software Foundation.
9  *
10  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
11  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
13  * details.
14  *
15  * You should have received a copy of the GNU General Public License along with
16  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
17  * Place, Suite 330, Boston, MA 02111-1307 USA
18  */
19 
20 #ifndef PALUDIS_GUARD_ARGS_ARGS_HANDLER_HH
21 #define PALUDIS_GUARD_ARGS_ARGS_HANDLER_HH 1
22 
23 #include <paludis/args/args_section.hh>
25 #include <paludis/util/iterator_range.hh>
26 #include <paludis/util/pimp.hh>
27 #include <paludis/util/options.hh>
28 #include <paludis/util/sequence.hh>
29 #include <memory>
30 #include <iosfwd>
31 #include <string>
32 
33 /** \file
34  * Declarations for ArgsHandler.
35  *
36  * \ingroup g_args
37  *
38  * \section Examples
39  *
40  * - None at this time.
41  */
42 
43 namespace paludis
44 {
45  namespace args
46  {
47  class ArgsOption;
48 
49 #include <paludis/args/args_handler-se.hh>
50 
52 
53  /**
54  * Handles command line arguments.
55  *
56  * \ingroup g_args
57  * \nosubgrouping
58  */
60  {
61  friend class ArgsSection;
62  friend std::ostream & operator<< (std::ostream &, const ArgsHandler &);
63 
64  private:
65  Pimp<ArgsHandler> _imp;
66 
67  protected:
68  /**
69  * Add a new usage line.
70  */
71  void add_usage_line(const std::string & l);
72 
73  /**
74  * Add a new environment line.
75  */
76  void add_environment_variable(const std::string & e, const std::string & desc);
77 
78  /**
79  * Add a new example.
80  */
81  void add_example(const std::string & e, const std::string & desc);
82 
83  /**
84  * Add a new note.
85  */
86  void add_note(const std::string &);
87 
88  /**
89  * Add a new description.
90  */
91  void add_description_line(const std::string & l);
92 
93  /**
94  * Add a 'see also' item.
95  *
96  * \since 0.48.2
97  */
98  void add_see_also(const std::string &, int section);
99 
100  /**
101  * Add an new ArgsSection (called by the ArgsSection constructor).
102  */
103  void add(ArgsSection * const);
104 
105  /**
106  * Dump, for --help output (called by operator<<).
107  */
108  void dump_to_stream(std::ostream & s) const;
109 
110  /**
111  * Called after run(), for convenience. Does nothing.
112  */
113  virtual void post_run();
114 
115  public:
116  ///\name Basic operations
117  ///\{
118 
119  ArgsHandler();
120 
121  virtual ~ArgsHandler();
122 
123  ArgsHandler(const ArgsHandler &) = delete;
124 
125  ArgsHandler & operator= (const ArgsHandler &) = delete;
126 
127  ///\}
128 
129  ///\name Iterate over our parameters (non - and -- switches and their values)
130  ///\{
131 
132  struct ParametersConstIteratorTag;
134 
135  ParametersConstIterator begin_parameters() const;
136  ParametersConstIterator end_parameters() const;
137 
138  IteratorRange<ParametersConstIterator> parameters() const {
139  return make_range(begin_parameters(), end_parameters());
140  }
141 
142  bool empty() const;
143 
144  /**
145  * If aho_separate_after_dashes, everything after a -- goes
146  * here.
147  *
148  * \since 0.47
149  */
150  const std::shared_ptr<const Sequence<std::string> > separate_after_dashes_args() const
151  PALUDIS_ATTRIBUTE((warn_unused_result));
152 
153  ///\}
154 
155  /**
156  * Add an ArgsOption instance.
157  */
158  void add_option(ArgsOption * const, const std::string & long_name,
159  const char short_name = '\0');
160 
161  /**
162  * Remove an ArgsOption instance.
163  */
164  void remove_option(const std::string & long_name, const char short_name = '\0');
165 
166  ///\name About our application (for documentation)
167  ///\{
168 
169  /**
170  * What is our application name?
171  */
172  virtual std::string app_name() const = 0;
173 
174  /**
175  * What is our application's Unix manual section?
176  */
177  virtual std::string man_section() const
178  {
179  return "1";
180  }
181 
182  /**
183  * One line synopsis of what our application is.
184  */
185  virtual std::string app_synopsis() const = 0;
186 
187  /**
188  * Long description of what our application is.
189  */
190  virtual std::string app_description() const = 0;
191 
192  ///\}
193 
194  ///\name Iterate over our usage lines (for documentation)
195  ///\{
196 
197  struct UsageLineConstIteratorTag;
199 
200  UsageLineConstIterator begin_usage_lines() const;
201  UsageLineConstIterator end_usage_lines() const;
202 
203  IteratorRange<UsageLineConstIterator> usage_lines() const {
204  return make_range(begin_usage_lines(), end_usage_lines());
205  }
206 
207  ///\}
208 
209  ///\name Iterate over our environment lines (for documentation)
210  ///\{
211 
212  struct EnvironmentLineConstIteratorTag;
213  typedef WrappedForwardIterator<EnvironmentLineConstIteratorTag,
214  const std::pair<std::string, std::string> > EnvironmentLineConstIterator;
215 
216  EnvironmentLineConstIterator begin_environment_lines() const;
217  EnvironmentLineConstIterator end_environment_lines() const;
218 
219  IteratorRange<EnvironmentLineConstIterator> environment_lines() const {
220  return make_range(begin_environment_lines(), end_environment_lines());
221  }
222 
223  ///\}
224 
225  ///\name Iterate over our examples (for documentation)
226  ///\{
227 
228  struct ExamplesConstIteratorTag;
229  typedef WrappedForwardIterator<ExamplesConstIteratorTag,
230  const std::pair<std::string, std::string> > ExamplesConstIterator;
231 
232  ExamplesConstIterator begin_examples() const;
233  ExamplesConstIterator end_examples() const;
234 
236  return make_range(begin_examples(), end_examples());
237  }
238 
239  ///\}
240 
241  ///\name Iterate over our sections
242  ///\{
243 
244  struct ArgsSectionsConstIteratorTag;
246 
247  ArgsSectionsConstIterator begin_args_sections() const;
248  ArgsSectionsConstIterator end_args_sections() const;
249 
250  IteratorRange<ArgsSectionsConstIterator> args_sections() const {
251  return make_range(begin_args_sections(), end_args_sections());
252  }
253 
254  /**
255  * The 'Options' section.
256  *
257  * Created if it does not exist.
258  */
259  ArgsSection * main_options_section() PALUDIS_ATTRIBUTE((warn_unused_result));
260 
261  ///\}
262 
263  ///\name Iterate over our notes
264  ///\{
265 
266  struct NotesIteratorTag;
268 
269  NotesIterator begin_notes() const;
270  NotesIterator end_notes() const;
271 
272  IteratorRange<NotesIterator> notes() const {
273  return make_range(begin_notes(), end_notes());
274  }
275 
276  ///\}
277 
278  ///\name Iterate over our extra description lines (for documentation)
279  ///\{
280 
281  struct DescriptionLineConstIteratorTag;
283 
284  DescriptionLineConstIterator begin_description_lines() const;
285  DescriptionLineConstIterator end_description_lines() const;
286 
287  IteratorRange<DescriptionLineConstIterator> description_lines() const {
288  return make_range(begin_description_lines(), end_description_lines());
289  }
290 
291  ///\}
292 
293  ///\name Iterate over our 'see also' lines
294  ///\since 0.48.2
295  ///\{
296 
297  struct SeeAlsoConstIteratorTag;
299 
300  SeeAlsoConstIterator begin_see_alsos() const;
301  SeeAlsoConstIterator end_see_alsos() const;
302 
303  IteratorRange<SeeAlsoConstIterator> see_alsos() const {
304  return make_range(begin_see_alsos(), end_see_alsos());
305  }
306 
307  ///\}
308 
309  ///\name For use by ArgsVisitor
310  ///\{
311 
312  struct ArgsIteratorTag;
314 
315  ///\}
316 
317  /**
318  * Parse command line arguments. The third argument is used to
319  * set PALUDIS_CLIENT. The fourth argument is the name of an
320  * environment variable holding arguments which are prepended
321  * to the command line arguments. The fifth argument is used as
322  * a prefix to export our command line via the environment.
323  */
324  void run(
325  const int argc,
326  const char * const * const argv,
327  const std::string & client,
328  const std::string & env_var,
329  const std::string & env_prefix,
330  const ArgsHandlerOptions & options = ArgsHandlerOptions());
331 
332  /**
333  * Parse command line arguments. The third argument is used to
334  * set PALUDIS_CLIENT. The fourth argument is the name of an
335  * environment variable holding arguments which are prepended
336  * to the command line arguments. The fifth argument is used as
337  * a prefix to export our command line via the environment.
338  */
339  void run(
340  const std::shared_ptr<const Sequence<std::string> > &,
341  const std::string & client,
342  const std::string & env_var,
343  const std::string & env_prefix,
344  const ArgsHandlerOptions & options = ArgsHandlerOptions());
345  };
346 
347  /**
348  * Output an ArgsHandler to an ostream, for --help output.
349  *
350  * \ingroup g_args
351  */
352  std::ostream & operator<< (std::ostream &, const ArgsHandler &) PALUDIS_VISIBLE;
353  }
354 
357  extern template class PALUDIS_VISIBLE WrappedForwardIterator<args::ArgsHandler::EnvironmentLineConstIteratorTag,
358  const std::pair<std::string, std::string> >;
359  extern template class PALUDIS_VISIBLE WrappedForwardIterator<args::ArgsHandler::ExamplesConstIteratorTag,
360  const std::pair<std::string, std::string> >;
366 }
367 
368 #endif
Definition: pimp.hh:51
Definition: about_metadata-fwd.hh:23
Definition: iterator_range.hh:28
std::ostream & operator<<(std::ostream &, const ArgsHandlerOption &) PALUDIS_VISIBLE
Definition: example_command_line.hh:15
Definition: sequence-fwd.hh:32
Definition: args_section.hh:41
Definition: wrapped_forward_iterator-fwd.hh:26
Definition: args_handler.hh:59
Definition: args_option.hh:74
Definition: options-fwd.hh:34
virtual std::string man_section() const
Definition: args_handler.hh:177
#define PALUDIS_ATTRIBUTE(x)
Definition: attributes.hh:53
#define PALUDIS_VISIBLE
Definition: attributes.hh:59