1 //===-- CommandLine.cpp - Command line parser implementation --------------===//
3 // This class implements a command line argument processor that is useful when
4 // creating a tool. It provides a simple, minimalistic interface that is easily
5 // extensible and supports nonlocal (library) command line options.
7 // Note that rather than trying to figure out what this code does, you could try
8 // reading the library documentation located in docs/CommandLine.html
10 //===----------------------------------------------------------------------===//
12 #include "Support/CommandLine.h"
13 #include "Support/STLExtras.h"
26 //===----------------------------------------------------------------------===//
27 // Basic, shared command line option processing machinery...
30 // Return the global command line option vector. Making it a function scoped
31 // static ensures that it will be initialized correctly before its first use.
33 static map<string, Option*> &getOpts() {
34 static map<string,Option*> CommandLineOptions;
35 return CommandLineOptions;
38 static vector<Option*> &getPositionalOpts() {
39 static vector<Option*> Positional;
43 static void AddArgument(const string &ArgName, Option *Opt) {
44 if (getOpts().find(ArgName) != getOpts().end()) {
45 cerr << "CommandLine Error: Argument '" << ArgName
46 << "' defined more than once!\n";
48 // Add argument to the argument map!
49 getOpts().insert(std::make_pair(ArgName, Opt));
53 static const char *ProgramName = 0;
54 static const char *ProgramOverview = 0;
56 static inline bool ProvideOption(Option *Handler, const char *ArgName,
57 const char *Value, int argc, char **argv,
59 // Enforce value requirements
60 switch (Handler->getValueExpectedFlag()) {
62 if (Value == 0 || *Value == 0) { // No value specified?
63 if (i+1 < argc) { // Steal the next argument, like for '-o filename'
66 return Handler->error(" requires a value!");
72 return Handler->error(" does not allow a value! '" +
73 string(Value) + "' specified.");
75 case ValueOptional: break;
76 default: cerr << "Bad ValueMask flag! CommandLine usage error:"
77 << Handler->getValueExpectedFlag() << "\n"; abort();
80 // Run the handler now!
81 return Handler->addOccurance(ArgName, Value);
84 static bool ProvidePositionalOption(Option *Handler, string &Arg) {
86 return ProvideOption(Handler, "", Arg.c_str(), 0, 0, Dummy);
90 // Option predicates...
91 static inline bool isGrouping(const Option *O) {
92 return O->getFormattingFlag() == cl::Grouping;
94 static inline bool isPrefixedOrGrouping(const Option *O) {
95 return isGrouping(O) || O->getFormattingFlag() == cl::Prefix;
98 // getOptionPred - Check to see if there are any options that satisfy the
99 // specified predicate with names that are the prefixes in Name. This is
100 // checked by progressively stripping characters off of the name, checking to
101 // see if there options that satisfy the predicate. If we find one, return it,
102 // otherwise return null.
104 static Option *getOptionPred(std::string Name, unsigned &Length,
105 bool (*Pred)(const Option*)) {
107 map<string, Option*>::iterator I = getOpts().find(Name);
108 if (I != getOpts().end() && Pred(I->second)) {
109 Length = Name.length();
113 if (Name.size() == 1) return 0;
115 Name.erase(Name.end()-1, Name.end()); // Chop off the last character...
116 I = getOpts().find(Name);
118 // Loop while we haven't found an option and Name still has at least two
119 // characters in it (so that the next iteration will not be the empty
121 } while ((I == getOpts().end() || !Pred(I->second)) && Name.size() > 1);
123 if (I != getOpts().end() && Pred(I->second)) {
124 Length = Name.length();
125 return I->second; // Found one!
127 return 0; // No option found!
130 static bool RequiresValue(const Option *O) {
131 return O->getNumOccurancesFlag() == cl::Required ||
132 O->getNumOccurancesFlag() == cl::OneOrMore;
135 static bool EatsUnboundedNumberOfValues(const Option *O) {
136 return O->getNumOccurancesFlag() == cl::ZeroOrMore ||
137 O->getNumOccurancesFlag() == cl::OneOrMore;
140 void cl::ParseCommandLineOptions(int &argc, char **argv,
141 const char *Overview) {
142 assert((!getOpts().empty() || !getPositionalOpts().empty()) &&
143 "No options specified, or ParseCommandLineOptions called more"
145 ProgramName = argv[0]; // Save this away safe and snug
146 ProgramOverview = Overview;
147 bool ErrorParsing = false;
149 map<string, Option*> &Opts = getOpts();
150 vector<Option*> &PositionalOpts = getPositionalOpts();
152 // Check out the positional arguments to collect information about them.
153 unsigned NumPositionalRequired = 0;
154 Option *ConsumeAfterOpt = 0;
155 if (!PositionalOpts.empty()) {
156 if (PositionalOpts[0]->getNumOccurancesFlag() == cl::ConsumeAfter) {
157 assert(PositionalOpts.size() > 1 &&
158 "Cannot specify cl::ConsumeAfter without a positional argument!");
159 ConsumeAfterOpt = PositionalOpts[0];
162 // Calculate how many positional values are _required_.
163 bool UnboundedFound = false;
164 for (unsigned i = ConsumeAfterOpt != 0, e = PositionalOpts.size();
166 Option *Opt = PositionalOpts[i];
167 if (RequiresValue(Opt))
168 ++NumPositionalRequired;
169 else if (ConsumeAfterOpt) {
170 // ConsumeAfter cannot be combined with "optional" positional options
171 // unless there is only one positional argument...
172 if (PositionalOpts.size() > 2)
174 Opt->error(" error - this positional option will never be matched, "
175 "because it does not Require a value, and a "
176 "cl::ConsumeAfter option is active!");
177 } else if (UnboundedFound) { // This option does not "require" a value...
178 // Make sure this option is not specified after an option that eats all
179 // extra arguments, or this one will never get any!
181 ErrorParsing |= Opt->error(" error - option can never match, because "
182 "another positional argument will match an "
183 "unbounded number of values, and this option"
184 " does not require a value!");
186 UnboundedFound |= EatsUnboundedNumberOfValues(Opt);
190 // PositionalVals - A vector of "positional" arguments we accumulate into to
191 // processes at the end...
193 vector<string> PositionalVals;
195 // Loop over all of the arguments... processing them.
196 bool DashDashFound = false; // Have we read '--'?
197 for (int i = 1; i < argc; ++i) {
199 const char *Value = "";
200 const char *ArgName = "";
202 // Check to see if this is a positional argument. This argument is
203 // considered to be positional if it doesn't start with '-', if it is "-"
204 // itself, or if we have see "--" already.
206 if (argv[i][0] != '-' || argv[i][1] == 0 || DashDashFound) {
207 // Positional argument!
208 if (!PositionalOpts.empty()) {
209 PositionalVals.push_back(argv[i]);
211 // All of the positional arguments have been fulfulled, give the rest to
212 // the consume after option... if it's specified...
214 if (PositionalVals.size() == NumPositionalRequired &&
215 ConsumeAfterOpt != 0) {
216 for (++i; i < argc; ++i)
217 PositionalVals.push_back(argv[i]);
218 break; // Handle outside of the argument processing loop...
221 // Delay processing positional arguments until the end...
224 } else { // We start with a '-', must be an argument...
226 while (*ArgName == '-') ++ArgName; // Eat leading dashes
228 if (*ArgName == 0 && !DashDashFound) { // Is this the mythical "--"?
229 DashDashFound = true; // Yup, take note of that fact...
230 continue; // Don't try to process it as an argument iself.
233 const char *ArgNameEnd = ArgName;
234 while (*ArgNameEnd && *ArgNameEnd != '=')
235 ++ArgNameEnd; // Scan till end of argument name...
238 if (*Value) // If we have an equals sign...
239 ++Value; // Advance to value...
242 string RealName(ArgName, ArgNameEnd);
243 // Extract arg name part
244 map<string, Option*>::iterator I = Opts.find(RealName);
246 if (I == Opts.end() && !*Value && RealName.size() > 1) {
247 // Check to see if this "option" is really a prefixed or grouped
251 Option *PGOpt = getOptionPred(RealName, Length, isPrefixedOrGrouping);
253 // If the option is a prefixed option, then the value is simply the
254 // rest of the name... so fall through to later processing, by
255 // setting up the argument name flags and value fields.
257 if (PGOpt && PGOpt->getFormattingFlag() == cl::Prefix) {
258 ArgNameEnd = ArgName+Length;
260 I = Opts.find(string(ArgName, ArgNameEnd));
261 assert(I->second == PGOpt);
263 // This must be a grouped option... handle all of them now...
264 assert(isGrouping(PGOpt) && "Broken getOptionPred!");
267 // Move current arg name out of RealName into RealArgName...
268 string RealArgName(RealName.begin(), RealName.begin()+Length);
269 RealName.erase(RealName.begin(), RealName.begin()+Length);
271 // Because ValueRequired is an invalid flag for grouped arguments,
272 // we don't need to pass argc/argv in...
274 assert(PGOpt->getValueExpectedFlag() != cl::ValueRequired &&
275 "Option can not be cl::Grouping AND cl::ValueRequired!");
277 ErrorParsing |= ProvideOption(PGOpt, RealArgName.c_str(), "",
280 // Get the next grouping option...
281 if (!RealName.empty())
282 PGOpt = getOptionPred(RealName, Length, isGrouping);
283 } while (!RealName.empty() && PGOpt);
285 if (RealName.empty()) // Processed all of the options, move on
286 continue; // to the next argv[] value...
288 // If RealName is not empty, that means we did not match one of the
289 // options! This is an error.
295 Handler = I != Opts.end() ? I->second : 0;
300 cerr << "Unknown command line argument '" << argv[i] << "'. Try: "
301 << argv[0] << " --help'\n";
306 ErrorParsing |= ProvideOption(Handler, ArgName, Value, argc, argv, i);
309 // Check and handle positional arguments now...
310 if (NumPositionalRequired > PositionalVals.size()) {
311 cerr << "Not enough positional command line arguments specified!\n";
312 cerr << "Must specify at least " << NumPositionalRequired
313 << " positional arguments: See: " << argv[0] << " --help\n";
317 } else if (ConsumeAfterOpt == 0) {
318 // Positional args have already been handled if ConsumeAfter is specified...
319 unsigned ValNo = 0, NumVals = PositionalVals.size();
320 for (unsigned i = 0, e = PositionalOpts.size(); i != e; ++i) {
321 if (RequiresValue(PositionalOpts[i])) {
322 ProvidePositionalOption(PositionalOpts[i], PositionalVals[ValNo++]);
323 --NumPositionalRequired; // We fulfilled our duty...
326 // If we _can_ give this option more arguments, do so now, as long as we
327 // do not give it values that others need. 'Done' controls whether the
328 // option even _WANTS_ any more.
330 bool Done = PositionalOpts[i]->getNumOccurancesFlag() == cl::Required;
331 while (NumVals-ValNo > NumPositionalRequired && !Done) {
332 switch (PositionalOpts[i]->getNumOccurancesFlag()) {
334 Done = true; // Optional arguments want _at most_ one value
336 case cl::ZeroOrMore: // Zero or more will take all they can get...
337 case cl::OneOrMore: // One or more will take all they can get...
338 ProvidePositionalOption(PositionalOpts[i], PositionalVals[ValNo++]);
341 assert(0 && "Internal error, unexpected NumOccurances flag in "
342 "positional argument processing!");
347 assert(ConsumeAfterOpt && NumPositionalRequired <= PositionalVals.size());
349 for (unsigned j = 1, e = PositionalOpts.size(); j != e; ++j)
350 if (RequiresValue(PositionalOpts[j]))
351 ErrorParsing |= ProvidePositionalOption(PositionalOpts[j],
352 PositionalVals[ValNo++]);
354 // Handle the case where there is just one positional option, and it's
355 // optional. In this case, we want to give JUST THE FIRST option to the
356 // positional option and keep the rest for the consume after. The above
357 // loop would have assigned no values to positional options in this case.
359 if (PositionalOpts.size() == 2 && ValNo == 0)
360 ErrorParsing |= ProvidePositionalOption(PositionalOpts[1],
361 PositionalVals[ValNo++]);
363 // Handle over all of the rest of the arguments to the
364 // cl::ConsumeAfter command line option...
365 for (; ValNo != PositionalVals.size(); ++ValNo)
366 ErrorParsing |= ProvidePositionalOption(ConsumeAfterOpt,
367 PositionalVals[ValNo]);
370 // Loop over args and make sure all required args are specified!
371 for (map<string, Option*>::iterator I = Opts.begin(),
372 E = Opts.end(); I != E; ++I) {
373 switch (I->second->getNumOccurancesFlag()) {
376 if (I->second->getNumOccurances() == 0) {
377 I->second->error(" must be specified at least once!");
386 // Free all of the memory allocated to the map. Command line options may only
387 // be processed once!
389 PositionalOpts.clear();
391 // If we had an error processing our arguments, don't let the program execute
392 if (ErrorParsing) exit(1);
395 //===----------------------------------------------------------------------===//
396 // Option Base class implementation
399 bool Option::error(string Message, const char *ArgName) {
400 if (ArgName == 0) ArgName = ArgStr;
402 cerr << HelpStr; // Be nice for positional arguments
404 cerr << "-" << ArgName;
405 cerr << " option" << Message << "\n";
409 bool Option::addOccurance(const char *ArgName, const string &Value) {
410 NumOccurances++; // Increment the number of times we have been seen
412 switch (getNumOccurancesFlag()) {
414 if (NumOccurances > 1)
415 return error(": may only occur zero or one times!", ArgName);
418 if (NumOccurances > 1)
419 return error(": must occur exactly one time!", ArgName);
423 case ConsumeAfter: break;
424 default: return error(": bad num occurances flag value!");
427 return handleOccurance(ArgName, Value);
430 // addArgument - Tell the system that this Option subclass will handle all
431 // occurances of -ArgStr on the command line.
433 void Option::addArgument(const char *ArgStr) {
435 AddArgument(ArgStr, this);
436 else if (getFormattingFlag() == Positional)
437 getPositionalOpts().push_back(this);
438 else if (getNumOccurancesFlag() == ConsumeAfter) {
439 assert((getPositionalOpts().empty() ||
440 getPositionalOpts().front()->getNumOccurancesFlag() != ConsumeAfter)
441 && "Cannot specify more than one option with cl::ConsumeAfter "
443 getPositionalOpts().insert(getPositionalOpts().begin(), this);
447 void Option::removeArgument(const char *ArgStr) {
449 assert(getOpts()[ArgStr] == this && "Arg not in map!");
450 getOpts().erase(ArgStr);
451 } else if (getFormattingFlag() == Positional) {
452 vector<Option*>::iterator I =
453 std::find(getPositionalOpts().begin(), getPositionalOpts().end(), this);
454 assert(I != getPositionalOpts().end() && "Arg not registered!");
455 getPositionalOpts().erase(I);
456 } else if (getNumOccurancesFlag() == ConsumeAfter) {
457 assert(!getPositionalOpts().empty() && getPositionalOpts()[0] == this &&
458 "Arg not registered correctly!");
459 getPositionalOpts().erase(getPositionalOpts().begin());
464 // getValueStr - Get the value description string, using "DefaultMsg" if nothing
465 // has been specified yet.
467 static const char *getValueStr(const Option &O, const char *DefaultMsg) {
468 if (O.ValueStr[0] == 0) return DefaultMsg;
472 //===----------------------------------------------------------------------===//
473 // cl::alias class implementation
476 // Return the width of the option tag for printing...
477 unsigned alias::getOptionWidth() const {
478 return std::strlen(ArgStr)+6;
481 // Print out the option for the alias...
482 void alias::printOptionInfo(unsigned GlobalWidth) const {
483 unsigned L = std::strlen(ArgStr);
484 cerr << " -" << ArgStr << string(GlobalWidth-L-6, ' ') << " - "
490 //===----------------------------------------------------------------------===//
491 // Parser Implementation code...
494 // parser<bool> implementation
496 bool parser<bool>::parseImpl(Option &O, const string &Arg, bool &Value) {
497 if (Arg == "" || Arg == "true" || Arg == "TRUE" || Arg == "True" ||
500 } else if (Arg == "false" || Arg == "FALSE" || Arg == "False" || Arg == "0") {
503 return O.error(": '" + Arg +
504 "' is invalid value for boolean argument! Try 0 or 1");
509 // Return the width of the option tag for printing...
510 unsigned parser<bool>::getOptionWidth(const Option &O) const {
511 return std::strlen(O.ArgStr)+6;
514 // printOptionInfo - Print out information about this option. The
515 // to-be-maintained width is specified.
517 void parser<bool>::printOptionInfo(const Option &O, unsigned GlobalWidth) const{
518 unsigned L = std::strlen(O.ArgStr);
519 cerr << " -" << O.ArgStr << string(GlobalWidth-L-6, ' ') << " - "
520 << O.HelpStr << "\n";
525 // parser<int> implementation
527 bool parser<int>::parseImpl(Option &O, const string &Arg, int &Value) {
528 const char *ArgStart = Arg.c_str();
530 Value = (int)strtol(ArgStart, &End, 0);
532 return O.error(": '" + Arg + "' value invalid for integer argument!");
536 // Return the width of the option tag for printing...
537 unsigned parser<int>::getOptionWidth(const Option &O) const {
538 return std::strlen(O.ArgStr)+std::strlen(getValueStr(O, "int"))+9;
541 // printOptionInfo - Print out information about this option. The
542 // to-be-maintained width is specified.
544 void parser<int>::printOptionInfo(const Option &O, unsigned GlobalWidth) const{
545 cerr << " -" << O.ArgStr << "=<" << getValueStr(O, "int") << ">"
546 << string(GlobalWidth-getOptionWidth(O), ' ') << " - "
547 << O.HelpStr << "\n";
551 // parser<double> implementation
553 bool parser<double>::parseImpl(Option &O, const string &Arg, double &Value) {
554 const char *ArgStart = Arg.c_str();
556 Value = strtod(ArgStart, &End);
558 return O.error(": '" +Arg+ "' value invalid for floating point argument!");
562 // Return the width of the option tag for printing...
563 unsigned parser<double>::getOptionWidth(const Option &O) const {
564 return std::strlen(O.ArgStr)+std::strlen(getValueStr(O, "number"))+9;
567 // printOptionInfo - Print out information about this option. The
568 // to-be-maintained width is specified.
570 void parser<double>::printOptionInfo(const Option &O,
571 unsigned GlobalWidth) const{
572 cerr << " -" << O.ArgStr << "=<" << getValueStr(O, "number") << ">"
573 << string(GlobalWidth-getOptionWidth(O), ' ')
574 << " - " << O.HelpStr << "\n";
578 // parser<string> implementation
581 // Return the width of the option tag for printing...
582 unsigned parser<string>::getOptionWidth(const Option &O) const {
583 return std::strlen(O.ArgStr)+std::strlen(getValueStr(O, "string"))+9;
586 // printOptionInfo - Print out information about this option. The
587 // to-be-maintained width is specified.
589 void parser<string>::printOptionInfo(const Option &O,
590 unsigned GlobalWidth) const{
591 cerr << " -" << O.ArgStr << " <" << getValueStr(O, "string") << ">"
592 << string(GlobalWidth-getOptionWidth(O), ' ')
593 << " - " << O.HelpStr << "\n";
596 // generic_parser_base implementation
599 // findOption - Return the option number corresponding to the specified
600 // argument string. If the option is not found, getNumOptions() is returned.
602 unsigned generic_parser_base::findOption(const char *Name) {
603 unsigned i = 0, e = getNumOptions();
607 if (getOption(i) == N)
615 // Return the width of the option tag for printing...
616 unsigned generic_parser_base::getOptionWidth(const Option &O) const {
618 unsigned Size = std::strlen(O.ArgStr)+6;
619 for (unsigned i = 0, e = getNumOptions(); i != e; ++i)
620 Size = std::max(Size, (unsigned)std::strlen(getOption(i))+8);
623 unsigned BaseSize = 0;
624 for (unsigned i = 0, e = getNumOptions(); i != e; ++i)
625 BaseSize = std::max(BaseSize, (unsigned)std::strlen(getOption(i))+8);
630 // printOptionInfo - Print out information about this option. The
631 // to-be-maintained width is specified.
633 void generic_parser_base::printOptionInfo(const Option &O,
634 unsigned GlobalWidth) const {
636 unsigned L = std::strlen(O.ArgStr);
637 cerr << " -" << O.ArgStr << string(GlobalWidth-L-6, ' ')
638 << " - " << O.HelpStr << "\n";
640 for (unsigned i = 0, e = getNumOptions(); i != e; ++i) {
641 unsigned NumSpaces = GlobalWidth-strlen(getOption(i))-8;
642 cerr << " =" << getOption(i) << string(NumSpaces, ' ') << " - "
643 << getDescription(i) << "\n";
647 cerr << " " << O.HelpStr << "\n";
648 for (unsigned i = 0, e = getNumOptions(); i != e; ++i) {
649 unsigned L = std::strlen(getOption(i));
650 cerr << " -" << getOption(i) << string(GlobalWidth-L-8, ' ') << " - "
651 << getDescription(i) << "\n";
657 //===----------------------------------------------------------------------===//
658 // --help and --help-hidden option implementation
664 const Option *EmptyArg;
665 const bool ShowHidden;
667 // isHidden/isReallyHidden - Predicates to be used to filter down arg lists.
668 inline static bool isHidden(pair<string, Option *> &OptPair) {
669 return OptPair.second->getOptionHiddenFlag() >= Hidden;
671 inline static bool isReallyHidden(pair<string, Option *> &OptPair) {
672 return OptPair.second->getOptionHiddenFlag() == ReallyHidden;
676 HelpPrinter(bool showHidden) : ShowHidden(showHidden) {
680 void operator=(bool Value) {
681 if (Value == false) return;
683 // Copy Options into a vector so we can sort them as we like...
684 vector<pair<string, Option*> > Options;
685 copy(getOpts().begin(), getOpts().end(), std::back_inserter(Options));
687 // Eliminate Hidden or ReallyHidden arguments, depending on ShowHidden
688 Options.erase(std::remove_if(Options.begin(), Options.end(),
689 std::ptr_fun(ShowHidden ? isReallyHidden : isHidden)),
692 // Eliminate duplicate entries in table (from enum flags options, f.e.)
693 { // Give OptionSet a scope
694 std::set<Option*> OptionSet;
695 for (unsigned i = 0; i != Options.size(); ++i)
696 if (OptionSet.count(Options[i].second) == 0)
697 OptionSet.insert(Options[i].second); // Add new entry to set
699 Options.erase(Options.begin()+i--); // Erase duplicate
703 cerr << "OVERVIEW:" << ProgramOverview << "\n";
705 cerr << "USAGE: " << ProgramName << " [options]";
707 // Print out the positional options...
708 vector<Option*> &PosOpts = getPositionalOpts();
709 Option *CAOpt = 0; // The cl::ConsumeAfter option, if it exists...
710 if (!PosOpts.empty() && PosOpts[0]->getNumOccurancesFlag() == ConsumeAfter)
713 for (unsigned i = CAOpt != 0, e = PosOpts.size(); i != e; ++i) {
714 cerr << " " << PosOpts[i]->HelpStr;
715 switch (PosOpts[i]->getNumOccurancesFlag()) {
716 case Optional: cerr << "?"; break;
717 case ZeroOrMore: cerr << "*"; break;
718 case Required: break;
719 case OneOrMore: cerr << "+"; break;
722 assert(0 && "Unknown NumOccurances Flag Value!");
726 // Print the consume after option info if it exists...
727 if (CAOpt) cerr << " " << CAOpt->HelpStr;
731 // Compute the maximum argument length...
733 for (unsigned i = 0, e = Options.size(); i != e; ++i)
734 MaxArgLen = std::max(MaxArgLen, Options[i].second->getOptionWidth());
736 cerr << "OPTIONS:\n";
737 for (unsigned i = 0, e = Options.size(); i != e; ++i)
738 Options[i].second->printOptionInfo(MaxArgLen);
740 // Halt the program if help information is printed
747 // Define the two HelpPrinter instances that are used to print out help, or
750 HelpPrinter NormalPrinter(false);
751 HelpPrinter HiddenPrinter(true);
753 cl::opt<HelpPrinter, true, parser<bool> >
754 HOp("help", cl::desc("display available options (--help-hidden for more)"),
755 cl::location(NormalPrinter));
757 cl::opt<HelpPrinter, true, parser<bool> >
758 HHOp("help-hidden", cl::desc("display all available options"),
759 cl::location(HiddenPrinter), cl::Hidden);
761 } // End anonymous namespace