A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
command-line.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License version 2 as
6 * published by the Free Software Foundation;
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 *
17 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
18 */
19#ifndef COMMAND_LINE_H
20#define COMMAND_LINE_H
21
22#include "callback.h"
23#include "nstime.h"
24#include "type-id.h"
25
26#include <memory> // shared_ptr
27#include <sstream>
28#include <string>
29#include <tuple>
30#include <vector>
31
32/**
33 * \file
34 * \ingroup commandline
35 * ns3::CommandLine declaration.
36 */
37
38namespace ns3
39{
40
41/**
42 * \ingroup core
43 * \defgroup commandline Command Line Parsing
44 *
45 * A uniform way to specify program documentation,
46 * allowed command line arguments and help strings,
47 * and set any attribute or global value, all from
48 * the command line directly.
49 *
50 * The main entry point is CommandLine
51 */
52
53/**
54 * \ingroup commandline
55 * \brief Parse command-line arguments
56 *
57 * Instances of this class can be used to parse command-line
58 * arguments. Programs can register a general usage message with
59 * CommandLine::Usage, and arguments with CommandLine::AddValue.
60 * Argument variable types with input streamers (`operator>>`)
61 * can be set directly; more complex argument parsing
62 * can be accomplished by providing a Callback.
63 *
64 * CommandLine also provides handlers for these standard arguments:
65 * \verbatim
66 --PrintGlobals: Print the list of globals.
67 --PrintGroups: Print the list of groups.
68 --PrintGroup=[group]: Print all TypeIds of group.
69 --PrintTypeIds: Print all TypeIds.
70 --PrintAttributes=[typeid]: Print all attributes of typeid.
71 --PrintVersion: Print the ns-3 version.
72 --PrintHelp: Print this help message. \endverbatim
73 *
74 * The more common \c \--version is a synonym for \c \--PrintVersion.
75 *
76 * The more common \c \--help is a synonym for \c \--PrintHelp; an example
77 * is given below.
78 *
79 * CommandLine can also handle non-option arguments
80 * (often called simply "positional" parameters: arguments which don't begin
81 * with "-" or "--"). These can be parsed directly in to variables,
82 * by registering arguments with AddNonOption in the order expected.
83 * Additional non-option arguments encountered will be captured as strings.
84 *
85 * Finally, CommandLine processes Attribute and GlobalValue arguments.
86 * Default values for specific attributes can be set using a shorthand
87 * argument name.
88 *
89 * In use, arguments are given in the form
90 * \verbatim
91 --arg=value --toggle first-non-option\endverbatim
92 * Most arguments expect a value, as in the first form, \c \--arg=value.
93 * Toggles, corresponding to boolean arguments, can be given in any of
94 * the forms
95 * \verbatim
96 --toggle1 --toggle2=1 --toggle3=t --toggle4=true \endverbatim
97 * The first form changes the state of toggle1 from its default;
98 * all the rest set the corresponding boolean variable to true.
99 * \c 0, \c f and \c false are accepted to set the variable to false.
100 * Option arguments can appear in any order on the command line,
101 * even intermixed with non-option arguments.
102 * The order of non-option arguments is preserved.
103 *
104 * Option arguments can be repeated on the command line; the last value given
105 * will be the final value used. For example,
106 * \verbatim
107 --arg=one --toggle=f --arg=another --toggle \endverbatim
108 * The variable set by \c \--arg will end up with the value \c "another";
109 * the boolean set by \c \--toggle will end up as \c true.
110 *
111 * Because arguments can be repeated it can be hard to decipher what
112 * value each variable ended up with, especially when using boolean toggles.
113 * Suggested best practice is for scripts to report the values of all items
114 * settable through CommandLine, as done by the example below.
115 *
116 *
117 * CommandLine can set the initial value of every attribute in the system
118 * with the \c \--TypeIdName::AttributeName=value syntax, for example
119 * \verbatim
120 --Application::StartTime=3s \endverbatim
121 * In some cases you may want to highlight the use of a particular
122 * attribute for a simulation script. For example, you might want
123 * to make it easy to set the \c Application::StartTime using
124 * the argument \c \--start, and have its help string show as part
125 * of the help message. This can be done using the
126 * \link AddValue(const std::string&, const std::string&) AddValue (name, attributePath) \endlink
127 * method.
128 *
129 * CommandLine can also set the value of every GlobalValue
130 * in the system with the \c \--GlobalValueName=value syntax, for example
131 * \verbatim
132 --SchedulerType=HeapScheduler \endverbatim
133 *
134 * A simple example of CommandLine is in `src/core/example/``command-line-example.cc`
135 * See that file for an example of handling non-option arguments.
136 *
137 * The heart of that example is this code:
138 *
139 * \code
140 * int intArg = 1;
141 * bool boolArg = false;
142 * std::string strArg = "strArg default";
143 *
144 * CommandLine cmd (__FILE__);
145 * cmd.Usage ("CommandLine example program.\n"
146 * "\n"
147 * "This little program demonstrates how to use CommandLine.");
148 * cmd.AddValue ("intArg", "an int argument", intArg);
149 * cmd.AddValue ("boolArg", "a bool argument", boolArg);
150 * cmd.AddValue ("strArg", "a string argument", strArg);
151 * cmd.AddValue ("anti", "ns3::RandomVariableStream::Antithetic");
152 * cmd.AddValue ("cbArg", "a string via callback", MakeCallback (SetCbArg));
153 * cmd.Parse (argc, argv);
154 * \endcode
155 * after which it prints the values of each variable. (The \c SetCbArg function
156 * is not shown here; see `src/core/example/``command-line-example.cc`)
157 *
158 * Here is the output from a few runs of that program:
159 *
160 * \verbatim
161 $ ./ns3 run "command-line-example"
162 intArg: 1
163 boolArg: false
164 strArg: "strArg default"
165 cbArg: "cbArg default"
166
167 $ ./ns3 run "command-line-example --intArg=2 --boolArg --strArg=Hello --cbArg=World"
168 intArg: 2
169 boolArg: true
170 strArg: "Hello"
171 cbArg: "World"
172
173 $ ./ns3 run "command-line-example --help"
174 ns3-dev-command-line-example-debug [Program Arguments] [General Arguments]
175
176 CommandLine example program.
177
178 This little program demonstrates how to use CommandLine.
179
180 Program Arguments:
181 --intArg: an int argument [1]
182 --boolArg: a bool argument [false]
183 --strArg: a string argument [strArg default]
184 --anti: Set this RNG stream to generate antithetic values
185 (ns3::RandomVariableStream::Antithetic) [false]
186 --cbArg: a string via callback
187
188 General Arguments:
189 --PrintGlobals: Print the list of globals.
190 --PrintGroups: Print the list of groups.
191 --PrintGroup=[group]: Print all TypeIds of group.
192 --PrintTypeIds: Print all TypeIds.
193 --PrintAttributes=[typeid]: Print all attributes of typeid.
194 --PrintVersion: Print the ns-3 version.
195 --PrintHelp: Print this help message. \endverbatim
196 *
197 * Having parsed the arguments, some programs will need to perform
198 * some additional validation of the received values. A common issue at this
199 * point is to discover that the supplied arguments are incomplete or
200 * incompatible. Suggested best practice is to supply an error message
201 * and the complete usage message. For example,
202 *
203 * \code
204 * int value1;
205 * int value2;
206 *
207 * CommandLine cmd (__FILE__);
208 * cmd.Usage ("...");
209 * cmd.AddValue ("value1", "first value", value1);
210 * cmd.AddValue ("value2", "second value", value1);
211 *
212 * cmd.Parse (argc, argv);
213 *
214 * if (value1 * value2 < 0)
215 * {
216 * std::cerr << "value1 and value2 must have the same sign!" << std::endl;
217 * std::cerr << cmd;
218 * exit (-1);
219 * }
220 * \endcode
221 *
222 * Finally, note that for examples which will be run by \c test.py
223 * the preferred declaration of a CommandLine instance is
224 *
225 * \code
226 * CommandLine cmd (__FILE__);
227 * \endcode
228 * This will ensure that the program usage and arguments can be added to
229 * the Doxygen documentation automatically.
230 */
232{
233 public:
234 /** Constructor */
235 CommandLine();
236 /**
237 * Construct and register the source file name.
238 * This would typically be called by
239 * CommandLine cmd (__FILE__);
240 *
241 * This form is required to generate Doxygen documentation of the
242 * arguments and options.
243 *
244 * \param [in] filename The source file name.
245 */
246 CommandLine(const std::string& filename);
247 /**
248 * Copy constructor
249 *
250 * \param [in] cmd The CommandLine to copy from
251 */
252 CommandLine(const CommandLine& cmd);
253 /**
254 * Assignment
255 *
256 * \param [in] cmd The CommandLine to assign from
257 * \return The CommandLine
258 */
259 CommandLine& operator=(const CommandLine& cmd);
260 /** Destructor */
261 ~CommandLine();
262
263 /**
264 * Supply the program usage and documentation.
265 *
266 * \param [in] usage Program usage message to write with \c \--help.
267 */
268 void Usage(const std::string& usage);
269
270 /**
271 * Add a program argument, assigning to POD
272 *
273 * \param [in] name The name of the program-supplied argument
274 * \param [in] help The help text used by \c \--PrintHelp
275 * \param [out] value A reference to the variable where the
276 * value parsed will be stored (if no value
277 * is parsed, this variable is not modified).
278 */
279 template <typename T>
280 void AddValue(const std::string& name, const std::string& help, T& value);
281
282 /**
283 * Retrieve the \c char* in \c char* and add it as a program argument
284 *
285 * This variant it used to receive C string pointers
286 * from the python bindings.
287 *
288 * The C string result stored in \c value will be null-terminated,
289 * and have a maximum length of \c (num - 1).
290 * The result will be truncated to fit, if necessary.
291 *
292 * \param [in] name The name of the program-supplied argument
293 * \param [in] help The help text used by \c \--PrintHelp
294 * \param [out] value A pointer pointing to the beginning
295 * of a null-terminated C string buffer provided by
296 * the caller. The parsed value will be stored in
297 * that buffer (if no value is parsed, this
298 * variable is not modified).
299 * \param num The size of the buffer pointed to by \c value,
300 * including any terminating null.
301 */
302 void AddValue(const std::string& name, const std::string& help, char* value, std::size_t num);
303 /**
304 * Callback function signature for
305 * AddValue(const std::string&,const std::string&,Callback<bool,const std::string>).
306 *
307 * \param [in] value The argument value.
308 */
309 typedef bool (*Callback)(const std::string& value);
310
311 /**
312 * Add a program argument, using a Callback to parse the value
313 *
314 * \param [in] name The name of the program-supplied argument
315 * \param [in] help The help text used by \c \--help
316 * \param [in] callback A Callback function that will be invoked to parse and
317 * store the value.
318 * \param [in] defaultValue Optional default value for argument.
319 *
320 * The callback should have the signature
321 * CommandLine::Callback
322 */
323 void AddValue(const std::string& name,
324 const std::string& help,
326 const std::string& defaultValue = "");
327
328 /**
329 * Add a program argument as a shorthand for an Attribute.
330 *
331 * \param [in] name The name of the program-supplied argument.
332 * \param [out] attributePath The fully-qualified name of the Attribute
333 */
334 void AddValue(const std::string& name, const std::string& attributePath);
335
336 /**
337 * Add a non-option argument, assigning to POD
338 *
339 * \param [in] name The name of the program-supplied argument
340 * \param [in] help The help text used by \c \--PrintHelp
341 * \param [out] value A reference to the variable where the
342 * value parsed will be stored (if no value
343 * is parsed, this variable is not modified).
344 */
345 template <typename T>
346 void AddNonOption(const std::string& name, const std::string& help, T& value);
347
348 /**
349 * Get extra non-option arguments by index.
350 * This allows CommandLine to accept more non-option arguments than
351 * have been configured explicitly with AddNonOption().
352 *
353 * This is only valid after calling Parse().
354 *
355 * \param [in] i The index of the non-option argument to return.
356 * \return The i'th non-option argument, as a string.
357 */
358 std::string GetExtraNonOption(std::size_t i) const;
359
360 /**
361 * Get the total number of non-option arguments found,
362 * including those configured with AddNonOption() and extra non-option
363 * arguments.
364 *
365 * This is only valid after calling Parse().
366 *
367 * \returns the number of non-option arguments found.
368 */
369 std::size_t GetNExtraNonOptions() const;
370
371 /**
372 * Parse the program arguments
373 *
374 * \param [in] argc The 'argc' variable: number of arguments (including the
375 * main program name as first element).
376 * \param [in] argv The 'argv' variable: a null-terminated array of strings,
377 * each of which identifies a command-line argument.
378 *
379 * Obviously, this method will parse the input command-line arguments and
380 * will attempt to handle them all.
381 *
382 * As a side effect, this method saves the program basename, which
383 * can be retrieved by GetName().
384 */
385 void Parse(int argc, char* argv[]);
386
387 /**
388 * Parse the program arguments.
389 *
390 * This version may be convenient when synthesizing arguments
391 * programmatically. Other than the type of argument this behaves
392 * identically to Parse(int, char *)
393 *
394 * \param [in] args The vector of arguments.
395 */
396 void Parse(std::vector<std::string> args);
397
398 /**
399 * Get the program name
400 *
401 * \return The program name. Only valid after calling Parse()
402 */
403 std::string GetName() const;
404
405 /**
406 * \brief Print program usage to the desired output stream
407 *
408 * Handler for \c \--PrintHelp and \c \--help: print Usage(), argument names, and help strings
409 *
410 * Alternatively, an overloaded operator << can be used:
411 * \code
412 * CommandLine cmd (__FILE__);
413 * cmd.Parse (argc, argv);
414 * ...
415 *
416 * std::cerr << cmd;
417 * \endcode
418 *
419 * \param [in,out] os The output stream to print on.
420 */
421 void PrintHelp(std::ostream& os) const;
422
423 /**
424 * Get the program version.
425 *
426 * \return The program version
427 */
428 std::string GetVersion() const;
429
430 /**
431 * Print ns-3 version to the desired output stream
432 *
433 * Handler for \c \--PrintVersion and \c \--version.
434 *
435 * \param [in,out] os The output stream to print on.
436 */
437 void PrintVersion(std::ostream& os) const;
438
439 private:
440 /**
441 * \ingroup commandline
442 * \brief The argument abstract base class
443 */
444 class Item
445 {
446 public:
447 std::string m_name; /**< Argument label: \c \--m_name=... */
448 std::string m_help; /**< Argument help string */
449 virtual ~Item(); /**< Destructor */
450 /**
451 * Parse from a string.
452 *
453 * \param [in] value The string representation
454 * \return \c true if parsing the value succeeded
455 */
456 virtual bool Parse(const std::string& value) const = 0;
457 /**
458 * \return \c true if this item has a default value.
459 */
460 virtual bool HasDefault() const;
461 /**
462 * \return The default value
463 */
464 virtual std::string GetDefault() const = 0;
465 }; // class Item
466
467 /**
468 * \ingroup commandline
469 *\brief An argument Item assigning to POD
470 */
471 template <typename T>
472 class UserItem : public Item
473 {
474 public:
475 // Inherited
476 bool Parse(const std::string& value) const override;
477 bool HasDefault() const override;
478 std::string GetDefault() const override;
479
480 T* m_valuePtr; /**< Pointer to the POD location */
481 std::string m_default; /**< String representation of default value */
482 }; // class UserItem
483
484 /**
485 * \ingroup commandline
486 * \brief Extension of Item for extra non-options, stored as strings.
487 */
488 class StringItem : public Item
489 {
490 public:
491 // Inherited
492 bool Parse(const std::string& value) const override;
493 bool HasDefault() const override;
494 std::string GetDefault() const override;
495
496 /**
497 * The argument value.
498 * \internal This has to be \c mutable because the Parse()
499 * function is \c const in the base class Item.
500 */
501 mutable std::string m_value;
502 }; // class StringItem
503
504 /**
505 * \ingroup commandline
506 * \brief Extension of Item for \c char*.
507 */
508 class CharStarItem : public Item
509 {
510 public:
511 // Inherited
512 bool Parse(const std::string& value) const override;
513 bool HasDefault() const override;
514 std::string GetDefault() const override;
515
516 /** The buffer to write in to. */
517 char* m_buffer;
518 /** The size of the buffer, including terminating null. */
519 std::size_t m_size;
520 /** The default value. */
521 std::string m_default;
522 }; // class CharStarItem
523
524 /**
525 * \ingroup commandline
526 * \brief An argument Item using a Callback to parse the input
527 */
528 class CallbackItem : public Item
529 {
530 public:
531 // Inherited
532 bool Parse(const std::string& value) const override;
533 bool HasDefault() const override;
534 std::string GetDefault() const override;
535
537 std::string m_default; /**< The default value, as a string, if it exists. */
538 }; // class CallbackItem
539
540 /**
541 * Tuple type returned by GetOptionName().
542 *
543 * | Field | Meaning
544 * |----------|--------------------------------------------
545 * | `get<0>` | Is this an option (beginning with `-`)?
546 * | `get<1>` | The option name (after any `-`, before `=`)
547 * | `get<2>` | The value (after any `=`)
548 */
549 using HasOptionName = std::tuple<bool, std::string, std::string>;
550
551 /**
552 * Strip leading `--` or `-` from options.
553 *
554 * \param [in] param Option name to search
555 * \returns \c false if none found, indicating this is a non-option.
556 */
557 HasOptionName GetOptionName(const std::string& param) const;
558 /**
559 * Handle hard-coded options.
560 *
561 * \note: if any hard-coded options are found this function exits.
562 *
563 * \param [in] args Vector of hard-coded options to handle.
564 */
565 void HandleHardOptions(const std::vector<std::string>& args) const;
566
567 /**
568 * Handle an option in the form \c param=value.
569 *
570 * \param [in] param The option string.
571 * \returns \c true if this was really an option.
572 */
573 bool HandleOption(const std::string& param) const;
574
575 /**
576 * Handle a non-option
577 *
578 * \param [in] value The command line non-option value.
579 * \return \c true if \c value could be parsed correctly.
580 */
581 bool HandleNonOption(const std::string& value);
582
583 /**
584 * Match name against the program or general arguments,
585 * and dispatch to the appropriate handler.
586 *
587 * \param [in] name The argument name
588 * \param [in] value The command line value
589 * \returns \c true if the argument was handled successfully
590 */
591 bool HandleArgument(const std::string& name, const std::string& value) const;
592 /**
593 * Callback function to handle attributes.
594 *
595 * \param [in] name The full name of the Attribute.
596 * \param [in] value The value to assign to \pname{name}.
597 * \return \c true if the value was set successfully, false otherwise.
598 */
599 static bool HandleAttribute(const std::string& name, const std::string& value);
600
601 /**
602 * Handler for \c \--PrintGlobals: print all global variables and values
603 * \param [in,out] os The output stream to print on.
604 */
605 void PrintGlobals(std::ostream& os) const;
606 /**
607 * Handler for \c \--PrintAttributes: print the attributes for a given type
608 * as well as its parents.
609 *
610 * \param [in,out] os the output stream.
611 * \param [in] type The type name whose Attributes should be displayed,
612 */
613 void PrintAttributes(std::ostream& os, const std::string& type) const;
614 /**
615 * Print the Attributes for a single type.
616 *
617 * \param [in,out] os the output stream.
618 * \param [in] tid The TypeId whose Attributes should be displayed,
619 * \param [in] header A header line to print if \c tid has Attributes
620 */
621 void PrintAttributeList(std::ostream& os, const TypeId tid, std::stringstream& header) const;
622 /**
623 * Handler for \c \--PrintGroup: print all types belonging to a given group.
624 *
625 * \param [in,out] os The output stream.
626 * \param [in] group The name of the TypeId group to display
627 */
628 void PrintGroup(std::ostream& os, const std::string& group) const;
629 /**
630 * Handler for \c \--PrintTypeIds: print all TypeId names.
631 *
632 * \param [in,out] os The output stream.
633 */
634 void PrintTypeIds(std::ostream& os) const;
635 /**
636 * Handler for \c \--PrintGroups: print all TypeId group names
637 *
638 * \param [in,out] os The output stream.
639 */
640 void PrintGroups(std::ostream& os) const;
641 /**
642 * Copy constructor implementation
643 *
644 * \param [in] cmd CommandLine to copy
645 */
646 void Copy(const CommandLine& cmd);
647 /** Remove all arguments, Usage(), name */
648 void Clear();
649 /**
650 * Append usage message in Doxygen format to the file indicated
651 * by the NS_COMMANDLINE_INTROSPECTION environment variable.
652 * This is typically only called once, by Parse().
653 */
654 void PrintDoxygenUsage() const;
655
656 /** Argument list container */
657 using Items = std::vector<std::shared_ptr<Item>>;
658
659 /** The list of option arguments */
661 /** The list of non-option arguments */
663
664 /** The expected number of non-option arguments */
665 std::size_t m_NNonOptions;
666 /** The number of actual non-option arguments seen so far. */
667 std::size_t m_nonOptionCount;
668 /** The Usage string */
669 std::string m_usage;
670 /** The source file name (without `.cc`), as would be given to `ns3 run` */
671 std::string m_shortName;
672
673}; // class CommandLine
674
675/** \ingroup commandline
676 * \defgroup commandlinehelper Helpers to specialize UserItem
677 */
678/**
679 * \ingroup commandlinehelper
680 * \brief Helpers for CommandLine to specialize UserItem
681 */
682namespace CommandLineHelper
683{
684
685/**
686 * \ingroup commandlinehelper
687 * \brief Helpers to specialize CommandLine::UserItem::Parse()
688 *
689 * \param [in] value The argument name
690 * \param [out] dest The argument location
691 * \tparam T \deduced The type being specialized
692 * \return \c true if parsing was successful
693 */
694template <typename T>
695bool UserItemParse(const std::string& value, T& dest);
696/**
697 * \brief Specialization of CommandLine::UserItem::Parse() to \c bool
698 *
699 * \param [in] value The argument name
700 * \param [out] dest The boolean variable to set
701 * \return \c true if parsing was successful
702 */
703template <>
704bool UserItemParse<bool>(const std::string& value, bool& dest);
705/**
706 * \brief Specialization of CommandLine::UserItem::Parse() to \c uint8_t
707 * to distinguish from \c char
708 *
709 * \param [in] value The argument name
710 * \param [out] dest The \c uint8_t variable to set
711 * \return \c true if parsing was successful
712 */
713template <>
714bool UserItemParse<uint8_t>(const std::string& value, uint8_t& dest);
715
716/**
717 * \ingroup commandlinehelper
718 * \brief Helper to specialize CommandLine::UserItem::GetDefault() on types
719 * needing special handling.
720 *
721 * \param [in] defaultValue The default value from the UserItem.
722 * \return The string representation of value.
723 * @{
724 */
725template <typename T>
726std::string GetDefault(const std::string& defaultValue);
727template <>
728std::string GetDefault<bool>(const std::string& defaultValue);
729template <>
730std::string GetDefault<Time>(const std::string& defaultValue);
731/**@}*/
732
733} // namespace CommandLineHelper
734
735} // namespace ns3
736
737/********************************************************************
738 * Implementation of the templates declared above.
739 ********************************************************************/
740
741namespace ns3
742{
743
744template <typename T>
745void
746CommandLine::AddValue(const std::string& name, const std::string& help, T& value)
747{
748 auto item = std::make_shared<UserItem<T>>();
749 item->m_name = name;
750 item->m_help = help;
751 item->m_valuePtr = &value;
752
753 std::stringstream ss;
754 ss << value;
755 ss >> item->m_default;
756
757 m_options.push_back(item);
758}
759
760template <typename T>
761void
762CommandLine::AddNonOption(const std::string& name, const std::string& help, T& value)
763{
764 auto item = std::make_shared<UserItem<T>>();
765 item->m_name = name;
766 item->m_help = help;
767 item->m_valuePtr = &value;
768
769 std::stringstream ss;
770 ss << value;
771 ss >> item->m_default;
772 m_nonOptions.push_back(item);
774}
775
776template <typename T>
777bool
779{
780 return !m_default.empty();
781}
782
783template <typename T>
784std::string
786{
787 return CommandLineHelper::GetDefault<T>(m_default);
788}
789
790template <typename T>
791std::string
792CommandLineHelper::GetDefault(const std::string& defaultValue)
793{
794 return defaultValue;
795}
796
797template <typename T>
798bool
799CommandLine::UserItem<T>::Parse(const std::string& value) const
800{
801 return CommandLineHelper::UserItemParse<T>(value, *m_valuePtr);
802}
803
804template <typename T>
805bool
806CommandLineHelper::UserItemParse(const std::string& value, T& dest)
807{
808 std::istringstream iss;
809 iss.str(value);
810 iss >> dest;
811 return !iss.bad() && !iss.fail();
812}
813
814/**
815 * Overloaded operator << to print program usage
816 * (shortcut for CommandLine::PrintHelper)
817 *
818 * \see CommandLine::PrintHelper
819 *
820 * Example usage:
821 * \code
822 * CommandLine cmd (__FILE__);
823 * cmd.Parse (argc, argv);
824 * ...
825 *
826 * std::cerr << cmd;
827 * \endcode
828 *
829 * \param [in,out] os The stream to print on.
830 * \param [in] cmd The CommandLine describing the program.
831 * \returns The stream.
832 */
833std::ostream& operator<<(std::ostream& os, const CommandLine& cmd);
834
835} // namespace ns3
836
837#endif /* COMMAND_LINE_H */
Declaration of the various callback functions.
Callback template class.
Definition: callback.h:438
An argument Item using a Callback to parse the input.
Definition: command-line.h:529
bool HasDefault() const override
std::string GetDefault() const override
bool Parse(const std::string &value) const override
Parse from a string.
std::string m_default
The default value, as a string, if it exists.
Definition: command-line.h:537
ns3::Callback< bool, const std::string & > m_callback
The Callback.
Definition: command-line.h:536
Extension of Item for char*.
Definition: command-line.h:509
char * m_buffer
The buffer to write in to.
Definition: command-line.h:517
std::string m_default
The default value.
Definition: command-line.h:521
bool Parse(const std::string &value) const override
Parse from a string.
std::string GetDefault() const override
std::size_t m_size
The size of the buffer, including terminating null.
Definition: command-line.h:519
bool HasDefault() const override
The argument abstract base class.
Definition: command-line.h:445
virtual bool Parse(const std::string &value) const =0
Parse from a string.
virtual ~Item()
Destructor.
virtual bool HasDefault() const
virtual std::string GetDefault() const =0
std::string m_name
Argument label: --m_name=...
Definition: command-line.h:447
std::string m_help
Argument help string.
Definition: command-line.h:448
Extension of Item for extra non-options, stored as strings.
Definition: command-line.h:489
bool Parse(const std::string &value) const override
Parse from a string.
std::string GetDefault() const override
std::string m_value
The argument value.
Definition: command-line.h:501
bool HasDefault() const override
An argument Item assigning to POD.
Definition: command-line.h:473
bool HasDefault() const override
Definition: command-line.h:778
std::string m_default
String representation of default value.
Definition: command-line.h:481
std::string GetDefault() const override
Definition: command-line.h:785
T * m_valuePtr
Pointer to the POD location.
Definition: command-line.h:480
bool Parse(const std::string &value) const override
Parse from a string.
Definition: command-line.h:799
Parse command-line arguments.
Definition: command-line.h:232
void PrintAttributeList(std::ostream &os, const TypeId tid, std::stringstream &header) const
Print the Attributes for a single type.
HasOptionName GetOptionName(const std::string &param) const
Strip leading -- or - from options.
std::tuple< bool, std::string, std::string > HasOptionName
Tuple type returned by GetOptionName().
Definition: command-line.h:549
void PrintGroups(std::ostream &os) const
Handler for --PrintGroups: print all TypeId group names.
void PrintTypeIds(std::ostream &os) const
Handler for --PrintTypeIds: print all TypeId names.
std::string GetExtraNonOption(std::size_t i) const
Get extra non-option arguments by index.
std::vector< std::shared_ptr< Item > > Items
Argument list container.
Definition: command-line.h:657
std::size_t m_nonOptionCount
The number of actual non-option arguments seen so far.
Definition: command-line.h:667
std::size_t GetNExtraNonOptions() const
Get the total number of non-option arguments found, including those configured with AddNonOption() an...
void PrintDoxygenUsage() const
Append usage message in Doxygen format to the file indicated by the NS_COMMANDLINE_INTROSPECTION envi...
~CommandLine()
Destructor.
std::string GetName() const
Get the program name.
Items m_options
The list of option arguments.
Definition: command-line.h:660
bool HandleNonOption(const std::string &value)
Handle a non-option.
void Parse(int argc, char *argv[])
Parse the program arguments.
void PrintGroup(std::ostream &os, const std::string &group) const
Handler for --PrintGroup: print all types belonging to a given group.
void Copy(const CommandLine &cmd)
Copy constructor implementation.
std::size_t m_NNonOptions
The expected number of non-option arguments.
Definition: command-line.h:665
void PrintGlobals(std::ostream &os) const
Handler for --PrintGlobals: print all global variables and values.
Items m_nonOptions
The list of non-option arguments.
Definition: command-line.h:662
void PrintVersion(std::ostream &os) const
Print ns-3 version to the desired output stream.
void HandleHardOptions(const std::vector< std::string > &args) const
Handle hard-coded options.
std::string m_shortName
The source file name (without .cc), as would be given to ns3 run
Definition: command-line.h:671
bool HandleOption(const std::string &param) const
Handle an option in the form param=value.
std::string m_usage
The Usage string.
Definition: command-line.h:669
void Clear()
Remove all arguments, Usage(), name.
void PrintAttributes(std::ostream &os, const std::string &type) const
Handler for --PrintAttributes: print the attributes for a given type as well as its parents.
bool HandleArgument(const std::string &name, const std::string &value) const
Match name against the program or general arguments, and dispatch to the appropriate handler.
void AddValue(const std::string &name, const std::string &help, T &value)
Add a program argument, assigning to POD.
Definition: command-line.h:746
static bool HandleAttribute(const std::string &name, const std::string &value)
Callback function to handle attributes.
CommandLine()
Constructor.
void PrintHelp(std::ostream &os) const
Print program usage to the desired output stream.
std::string GetVersion() const
Get the program version.
void AddNonOption(const std::string &name, const std::string &help, T &value)
Add a non-option argument, assigning to POD.
Definition: command-line.h:762
CommandLine & operator=(const CommandLine &cmd)
Assignment.
void Usage(const std::string &usage)
Supply the program usage and documentation.
a unique identifier for an interface.
Definition: type-id.h:59
std::string GetDefault< Time >(const std::string &defaultValue)
Helper to specialize CommandLine::UserItem::GetDefault() on types needing special handling.
bool UserItemParse(const std::string &value, T &dest)
Helpers to specialize CommandLine::UserItem::Parse()
Definition: command-line.h:806
std::string GetDefault< bool >(const std::string &defaultValue)
Helper to specialize CommandLine::UserItem::GetDefault() on types needing special handling.
std::string GetDefault(const std::string &defaultValue)
Helper to specialize CommandLine::UserItem::GetDefault() on types needing special handling.
Definition: command-line.h:792
bool UserItemParse< bool >(const std::string &value, bool &dest)
Specialization of CommandLine::UserItem::Parse() to bool.
bool UserItemParse< uint8_t >(const std::string &value, uint8_t &dest)
Specialization of CommandLine::UserItem::Parse() to uint8_t to distinguish from char.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition: angles.cc:159
Declaration of classes ns3::Time and ns3::TimeWithUnit, and the TimeValue implementation classes.
ns3::TypeId declaration; inline and template implementations.