1 //===- llvm/Support/CommandLine.h - Command line handler --------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // This class implements a command line argument processor that is useful when
10 // creating a tool.  It provides a simple, minimalistic interface that is easily
11 // extensible and supports nonlocal (library) command line options.
12 //
13 // Note that rather than trying to figure out what this code does, you should
14 // read the library documentation located in docs/CommandLine.html or looks at
15 // the many example usages in tools/*/*.cpp
16 //
17 //===----------------------------------------------------------------------===//
18 
19 #ifndef LLVM_SUPPORT_COMMANDLINE_H
20 #define LLVM_SUPPORT_COMMANDLINE_H
21 
22 #include "llvm/ADT/ArrayRef.h"
23 #include "llvm/ADT/STLExtras.h"
24 #include "llvm/ADT/SmallPtrSet.h"
25 #include "llvm/ADT/SmallVector.h"
26 #include "llvm/ADT/StringMap.h"
27 #include "llvm/ADT/StringRef.h"
28 #include "llvm/ADT/Twine.h"
29 #include "llvm/ADT/iterator_range.h"
30 #include "llvm/Support/ErrorHandling.h"
31 #include "llvm/Support/ManagedStatic.h"
32 #include "llvm/Support/StringSaver.h"
33 #include "llvm/Support/raw_ostream.h"
34 #include <cassert>
35 #include <climits>
36 #include <cstddef>
37 #include <functional>
38 #include <initializer_list>
39 #include <string>
40 #include <type_traits>
41 #include <vector>
42 
43 namespace llvm {
44 
45 namespace vfs {
46 class FileSystem;
47 }
48 
49 class StringSaver;
50 
51 /// This namespace contains all of the command line option processing machinery.
52 /// It is intentionally a short name to make qualified usage concise.
53 namespace cl {
54 
55 //===----------------------------------------------------------------------===//
56 // Command line option processing entry point.
57 //
58 // Returns true on success. Otherwise, this will print the error message to
59 // stderr and exit if \p Errs is not set (nullptr by default), or print the
60 // error message to \p Errs and return false if \p Errs is provided.
61 //
62 // If EnvVar is not nullptr, command-line options are also parsed from the
63 // environment variable named by EnvVar.  Precedence is given to occurrences
64 // from argv.  This precedence is currently implemented by parsing argv after
65 // the environment variable, so it is only implemented correctly for options
66 // that give precedence to later occurrences.  If your program supports options
67 // that give precedence to earlier occurrences, you will need to extend this
68 // function to support it correctly.
69 bool ParseCommandLineOptions(int argc, const char *const *argv,
70                              StringRef Overview = "",
71                              raw_ostream *Errs = nullptr,
72                              const char *EnvVar = nullptr,
73                              bool LongOptionsUseDoubleDash = false);
74 
75 // Function pointer type for printing version information.
76 using VersionPrinterTy = std::function<void(raw_ostream &)>;
77 
78 ///===---------------------------------------------------------------------===//
79 /// Override the default (LLVM specific) version printer used to print out the
80 /// version when --version is given on the command line. This allows other
81 /// systems using the CommandLine utilities to print their own version string.
82 void SetVersionPrinter(VersionPrinterTy func);
83 
84 ///===---------------------------------------------------------------------===//
85 /// Add an extra printer to use in addition to the default one. This can be
86 /// called multiple times, and each time it adds a new function to the list
87 /// which will be called after the basic LLVM version printing is complete.
88 /// Each can then add additional information specific to the tool.
89 void AddExtraVersionPrinter(VersionPrinterTy func);
90 
91 // Print option values.
92 // With -print-options print the difference between option values and defaults.
93 // With -print-all-options print all option values.
94 // (Currently not perfect, but best-effort.)
95 void PrintOptionValues();
96 
97 // Forward declaration - AddLiteralOption needs to be up here to make gcc happy.
98 class Option;
99 
100 /// Adds a new option for parsing and provides the option it refers to.
101 ///
102 /// \param O pointer to the option
103 /// \param Name the string name for the option to handle during parsing
104 ///
105 /// Literal options are used by some parsers to register special option values.
106 /// This is how the PassNameParser registers pass names for opt.
107 void AddLiteralOption(Option &O, StringRef Name);
108 
109 //===----------------------------------------------------------------------===//
110 // Flags permitted to be passed to command line arguments
111 //
112 
113 enum NumOccurrencesFlag { // Flags for the number of occurrences allowed
114   Optional = 0x00,        // Zero or One occurrence
115   ZeroOrMore = 0x01,      // Zero or more occurrences allowed
116   Required = 0x02,        // One occurrence required
117   OneOrMore = 0x03,       // One or more occurrences required
118 
119   // Indicates that this option is fed anything that follows the last positional
120   // argument required by the application (it is an error if there are zero
121   // positional arguments, and a ConsumeAfter option is used).
122   // Thus, for example, all arguments to LLI are processed until a filename is
123   // found.  Once a filename is found, all of the succeeding arguments are
124   // passed, unprocessed, to the ConsumeAfter option.
125   //
126   ConsumeAfter = 0x04
127 };
128 
129 enum ValueExpected { // Is a value required for the option?
130   // zero reserved for the unspecified value
131   ValueOptional = 0x01,  // The value can appear... or not
132   ValueRequired = 0x02,  // The value is required to appear!
133   ValueDisallowed = 0x03 // A value may not be specified (for flags)
134 };
135 
136 enum OptionHidden {   // Control whether -help shows this option
137   NotHidden = 0x00,   // Option included in -help & -help-hidden
138   Hidden = 0x01,      // -help doesn't, but -help-hidden does
139   ReallyHidden = 0x02 // Neither -help nor -help-hidden show this arg
140 };
141 
142 // This controls special features that the option might have that cause it to be
143 // parsed differently...
144 //
145 // Prefix - This option allows arguments that are otherwise unrecognized to be
146 // matched by options that are a prefix of the actual value.  This is useful for
147 // cases like a linker, where options are typically of the form '-lfoo' or
148 // '-L../../include' where -l or -L are the actual flags.  When prefix is
149 // enabled, and used, the value for the flag comes from the suffix of the
150 // argument.
151 //
152 // AlwaysPrefix - Only allow the behavior enabled by the Prefix flag and reject
153 // the Option=Value form.
154 //
155 
156 enum FormattingFlags {
157   NormalFormatting = 0x00, // Nothing special
158   Positional = 0x01,       // Is a positional argument, no '-' required
159   Prefix = 0x02,           // Can this option directly prefix its value?
160   AlwaysPrefix = 0x03      // Can this option only directly prefix its value?
161 };
162 
163 enum MiscFlags {             // Miscellaneous flags to adjust argument
164   CommaSeparated = 0x01,     // Should this cl::list split between commas?
165   PositionalEatsArgs = 0x02, // Should this positional cl::list eat -args?
166   Sink = 0x04,               // Should this cl::list eat all unknown options?
167 
168   // Can this option group with other options?
169   // If this is enabled, multiple letter options are allowed to bunch together
170   // with only a single hyphen for the whole group.  This allows emulation
171   // of the behavior that ls uses for example: ls -la === ls -l -a
172   Grouping = 0x08,
173 
174   // Default option
175   DefaultOption = 0x10
176 };
177 
178 //===----------------------------------------------------------------------===//
179 //
180 class OptionCategory {
181 private:
182   StringRef const Name;
183   StringRef const Description;
184 
185   void registerCategory();
186 
187 public:
188   OptionCategory(StringRef const Name,
189                  StringRef const Description = "")
Name(Name)190       : Name(Name), Description(Description) {
191     registerCategory();
192   }
193 
getName()194   StringRef getName() const { return Name; }
getDescription()195   StringRef getDescription() const { return Description; }
196 };
197 
198 // The general Option Category (used as default category).
199 OptionCategory &getGeneralCategory();
200 
201 //===----------------------------------------------------------------------===//
202 //
203 class SubCommand {
204 private:
205   StringRef Name;
206   StringRef Description;
207 
208 protected:
209   void registerSubCommand();
210   void unregisterSubCommand();
211 
212 public:
213   SubCommand(StringRef Name, StringRef Description = "")
Name(Name)214       : Name(Name), Description(Description) {
215         registerSubCommand();
216   }
217   SubCommand() = default;
218 
219   // Get the special subcommand representing no subcommand.
220   static SubCommand &getTopLevel();
221 
222   // Get the special subcommand that can be used to put an option into all
223   // subcomands.
224   static SubCommand &getAll();
225 
226   void reset();
227 
228   explicit operator bool() const;
229 
getName()230   StringRef getName() const { return Name; }
getDescription()231   StringRef getDescription() const { return Description; }
232 
233   SmallVector<Option *, 4> PositionalOpts;
234   SmallVector<Option *, 4> SinkOpts;
235   StringMap<Option *> OptionsMap;
236 
237   Option *ConsumeAfterOpt = nullptr; // The ConsumeAfter option if it exists.
238 };
239 
240 // A special subcommand representing no subcommand
241 extern ManagedStatic<SubCommand> TopLevelSubCommand;
242 
243 // A special subcommand that can be used to put an option into all subcommands.
244 extern ManagedStatic<SubCommand> AllSubCommands;
245 
246 //===----------------------------------------------------------------------===//
247 //
248 class Option {
249   friend class alias;
250 
251   // Overriden by subclasses to handle the value passed into an argument. Should
252   // return true if there was an error processing the argument and the program
253   // should exit.
254   //
255   virtual bool handleOccurrence(unsigned pos, StringRef ArgName,
256                                 StringRef Arg) = 0;
257 
getValueExpectedFlagDefault()258   virtual enum ValueExpected getValueExpectedFlagDefault() const {
259     return ValueOptional;
260   }
261 
262   // Out of line virtual function to provide home for the class.
263   virtual void anchor();
264 
265   uint16_t NumOccurrences; // The number of times specified
266   // Occurrences, HiddenFlag, and Formatting are all enum types but to avoid
267   // problems with signed enums in bitfields.
268   uint16_t Occurrences : 3; // enum NumOccurrencesFlag
269   // not using the enum type for 'Value' because zero is an implementation
270   // detail representing the non-value
271   uint16_t Value : 2;
272   uint16_t HiddenFlag : 2; // enum OptionHidden
273   uint16_t Formatting : 2; // enum FormattingFlags
274   uint16_t Misc : 5;
275   uint16_t FullyInitialized : 1; // Has addArgument been called?
276   uint16_t Position;             // Position of last occurrence of the option
277   uint16_t AdditionalVals;       // Greater than 0 for multi-valued option.
278 
279 public:
280   StringRef ArgStr;   // The argument string itself (ex: "help", "o")
281   StringRef HelpStr;  // The descriptive text message for -help
282   StringRef ValueStr; // String describing what the value of this option is
283   SmallVector<OptionCategory *, 1>
284       Categories;                    // The Categories this option belongs to
285   SmallPtrSet<SubCommand *, 1> Subs; // The subcommands this option belongs to.
286 
getNumOccurrencesFlag()287   inline enum NumOccurrencesFlag getNumOccurrencesFlag() const {
288     return (enum NumOccurrencesFlag)Occurrences;
289   }
290 
getValueExpectedFlag()291   inline enum ValueExpected getValueExpectedFlag() const {
292     return Value ? ((enum ValueExpected)Value) : getValueExpectedFlagDefault();
293   }
294 
getOptionHiddenFlag()295   inline enum OptionHidden getOptionHiddenFlag() const {
296     return (enum OptionHidden)HiddenFlag;
297   }
298 
getFormattingFlag()299   inline enum FormattingFlags getFormattingFlag() const {
300     return (enum FormattingFlags)Formatting;
301   }
302 
getMiscFlags()303   inline unsigned getMiscFlags() const { return Misc; }
getPosition()304   inline unsigned getPosition() const { return Position; }
getNumAdditionalVals()305   inline unsigned getNumAdditionalVals() const { return AdditionalVals; }
306 
307   // Return true if the argstr != ""
hasArgStr()308   bool hasArgStr() const { return !ArgStr.empty(); }
isPositional()309   bool isPositional() const { return getFormattingFlag() == cl::Positional; }
isSink()310   bool isSink() const { return getMiscFlags() & cl::Sink; }
isDefaultOption()311   bool isDefaultOption() const { return getMiscFlags() & cl::DefaultOption; }
312 
isConsumeAfter()313   bool isConsumeAfter() const {
314     return getNumOccurrencesFlag() == cl::ConsumeAfter;
315   }
316 
isInAllSubCommands()317   bool isInAllSubCommands() const {
318     return llvm::is_contained(Subs, &SubCommand::getAll());
319   }
320 
321   //-------------------------------------------------------------------------===
322   // Accessor functions set by OptionModifiers
323   //
324   void setArgStr(StringRef S);
setDescription(StringRef S)325   void setDescription(StringRef S) { HelpStr = S; }
setValueStr(StringRef S)326   void setValueStr(StringRef S) { ValueStr = S; }
setNumOccurrencesFlag(enum NumOccurrencesFlag Val)327   void setNumOccurrencesFlag(enum NumOccurrencesFlag Val) { Occurrences = Val; }
setValueExpectedFlag(enum ValueExpected Val)328   void setValueExpectedFlag(enum ValueExpected Val) { Value = Val; }
setHiddenFlag(enum OptionHidden Val)329   void setHiddenFlag(enum OptionHidden Val) { HiddenFlag = Val; }
setFormattingFlag(enum FormattingFlags V)330   void setFormattingFlag(enum FormattingFlags V) { Formatting = V; }
setMiscFlag(enum MiscFlags M)331   void setMiscFlag(enum MiscFlags M) { Misc |= M; }
setPosition(unsigned pos)332   void setPosition(unsigned pos) { Position = pos; }
333   void addCategory(OptionCategory &C);
addSubCommand(SubCommand & S)334   void addSubCommand(SubCommand &S) { Subs.insert(&S); }
335 
336 protected:
Option(enum NumOccurrencesFlag OccurrencesFlag,enum OptionHidden Hidden)337   explicit Option(enum NumOccurrencesFlag OccurrencesFlag,
338                   enum OptionHidden Hidden)
339       : NumOccurrences(0), Occurrences(OccurrencesFlag), Value(0),
340         HiddenFlag(Hidden), Formatting(NormalFormatting), Misc(0),
341         FullyInitialized(false), Position(0), AdditionalVals(0) {
342     Categories.push_back(&getGeneralCategory());
343   }
344 
setNumAdditionalVals(unsigned n)345   inline void setNumAdditionalVals(unsigned n) { AdditionalVals = n; }
346 
347 public:
348   virtual ~Option() = default;
349 
350   // Register this argument with the commandline system.
351   //
352   void addArgument();
353 
354   /// Unregisters this option from the CommandLine system.
355   ///
356   /// This option must have been the last option registered.
357   /// For testing purposes only.
358   void removeArgument();
359 
360   // Return the width of the option tag for printing...
361   virtual size_t getOptionWidth() const = 0;
362 
363   // Print out information about this option. The to-be-maintained width is
364   // specified.
365   //
366   virtual void printOptionInfo(size_t GlobalWidth) const = 0;
367 
368   virtual void printOptionValue(size_t GlobalWidth, bool Force) const = 0;
369 
370   virtual void setDefault() = 0;
371 
372   // Prints the help string for an option.
373   //
374   // This maintains the Indent for multi-line descriptions.
375   // FirstLineIndentedBy is the count of chars of the first line
376   //      i.e. the one containing the --<option name>.
377   static void printHelpStr(StringRef HelpStr, size_t Indent,
378                            size_t FirstLineIndentedBy);
379 
380   // Prints the help string for an enum value.
381   //
382   // This maintains the Indent for multi-line descriptions.
383   // FirstLineIndentedBy is the count of chars of the first line
384   //      i.e. the one containing the =<value>.
385   static void printEnumValHelpStr(StringRef HelpStr, size_t Indent,
386                                   size_t FirstLineIndentedBy);
387 
getExtraOptionNames(SmallVectorImpl<StringRef> &)388   virtual void getExtraOptionNames(SmallVectorImpl<StringRef> &) {}
389 
390   // Wrapper around handleOccurrence that enforces Flags.
391   //
392   virtual bool addOccurrence(unsigned pos, StringRef ArgName, StringRef Value,
393                              bool MultiArg = false);
394 
395   // Prints option name followed by message.  Always returns true.
396   bool error(const Twine &Message, StringRef ArgName = StringRef(), raw_ostream &Errs = llvm::errs());
error(const Twine & Message,raw_ostream & Errs)397   bool error(const Twine &Message, raw_ostream &Errs) {
398     return error(Message, StringRef(), Errs);
399   }
400 
getNumOccurrences()401   inline int getNumOccurrences() const { return NumOccurrences; }
402   void reset();
403 };
404 
405 //===----------------------------------------------------------------------===//
406 // Command line option modifiers that can be used to modify the behavior of
407 // command line option parsers...
408 //
409 
410 // Modifier to set the description shown in the -help output...
411 struct desc {
412   StringRef Desc;
413 
descdesc414   desc(StringRef Str) : Desc(Str) {}
415 
applydesc416   void apply(Option &O) const { O.setDescription(Desc); }
417 };
418 
419 // Modifier to set the value description shown in the -help output...
420 struct value_desc {
421   StringRef Desc;
422 
value_descvalue_desc423   value_desc(StringRef Str) : Desc(Str) {}
424 
applyvalue_desc425   void apply(Option &O) const { O.setValueStr(Desc); }
426 };
427 
428 // Specify a default (initial) value for the command line argument, if the
429 // default constructor for the argument type does not give you what you want.
430 // This is only valid on "opt" arguments, not on "list" arguments.
431 template <class Ty> struct initializer {
432   const Ty &Init;
initializerinitializer433   initializer(const Ty &Val) : Init(Val) {}
434 
applyinitializer435   template <class Opt> void apply(Opt &O) const { O.setInitialValue(Init); }
436 };
437 
438 template <class Ty> struct list_initializer {
439   ArrayRef<Ty> Inits;
list_initializerlist_initializer440   list_initializer(ArrayRef<Ty> Vals) : Inits(Vals) {}
441 
applylist_initializer442   template <class Opt> void apply(Opt &O) const { O.setInitialValues(Inits); }
443 };
444 
init(const Ty & Val)445 template <class Ty> initializer<Ty> init(const Ty &Val) {
446   return initializer<Ty>(Val);
447 }
448 
449 template <class Ty>
list_init(ArrayRef<Ty> Vals)450 list_initializer<Ty> list_init(ArrayRef<Ty> Vals) {
451   return list_initializer<Ty>(Vals);
452 }
453 
454 // Allow the user to specify which external variable they want to store the
455 // results of the command line argument processing into, if they don't want to
456 // store it in the option itself.
457 template <class Ty> struct LocationClass {
458   Ty &Loc;
459 
LocationClassLocationClass460   LocationClass(Ty &L) : Loc(L) {}
461 
applyLocationClass462   template <class Opt> void apply(Opt &O) const { O.setLocation(O, Loc); }
463 };
464 
location(Ty & L)465 template <class Ty> LocationClass<Ty> location(Ty &L) {
466   return LocationClass<Ty>(L);
467 }
468 
469 // Specify the Option category for the command line argument to belong to.
470 struct cat {
471   OptionCategory &Category;
472 
catcat473   cat(OptionCategory &c) : Category(c) {}
474 
applycat475   template <class Opt> void apply(Opt &O) const { O.addCategory(Category); }
476 };
477 
478 // Specify the subcommand that this option belongs to.
479 struct sub {
480   SubCommand &Sub;
481 
subsub482   sub(SubCommand &S) : Sub(S) {}
483 
applysub484   template <class Opt> void apply(Opt &O) const { O.addSubCommand(Sub); }
485 };
486 
487 // Specify a callback function to be called when an option is seen.
488 // Can be used to set other options automatically.
489 template <typename R, typename Ty> struct cb {
490   std::function<R(Ty)> CB;
491 
cbcb492   cb(std::function<R(Ty)> CB) : CB(CB) {}
493 
applycb494   template <typename Opt> void apply(Opt &O) const { O.setCallback(CB); }
495 };
496 
497 namespace detail {
498 template <typename F>
499 struct callback_traits : public callback_traits<decltype(&F::operator())> {};
500 
501 template <typename R, typename C, typename... Args>
502 struct callback_traits<R (C::*)(Args...) const> {
503   using result_type = R;
504   using arg_type = std::tuple_element_t<0, std::tuple<Args...>>;
505   static_assert(sizeof...(Args) == 1, "callback function must have one and only one parameter");
506   static_assert(std::is_same<result_type, void>::value,
507                 "callback return type must be void");
508   static_assert(std::is_lvalue_reference<arg_type>::value &&
509                     std::is_const<std::remove_reference_t<arg_type>>::value,
510                 "callback arg_type must be a const lvalue reference");
511 };
512 } // namespace detail
513 
514 template <typename F>
515 cb<typename detail::callback_traits<F>::result_type,
516    typename detail::callback_traits<F>::arg_type>
517 callback(F CB) {
518   using result_type = typename detail::callback_traits<F>::result_type;
519   using arg_type = typename detail::callback_traits<F>::arg_type;
520   return cb<result_type, arg_type>(CB);
521 }
522 
523 //===----------------------------------------------------------------------===//
524 
525 // Support value comparison outside the template.
526 struct GenericOptionValue {
527   virtual bool compare(const GenericOptionValue &V) const = 0;
528 
529 protected:
530   GenericOptionValue() = default;
531   GenericOptionValue(const GenericOptionValue&) = default;
532   GenericOptionValue &operator=(const GenericOptionValue &) = default;
533   ~GenericOptionValue() = default;
534 
535 private:
536   virtual void anchor();
537 };
538 
539 template <class DataType> struct OptionValue;
540 
541 // The default value safely does nothing. Option value printing is only
542 // best-effort.
543 template <class DataType, bool isClass>
544 struct OptionValueBase : public GenericOptionValue {
545   // Temporary storage for argument passing.
546   using WrapperType = OptionValue<DataType>;
547 
548   bool hasValue() const { return false; }
549 
550   const DataType &getValue() const { llvm_unreachable("no default value"); }
551 
552   // Some options may take their value from a different data type.
553   template <class DT> void setValue(const DT & /*V*/) {}
554 
555   bool compare(const DataType & /*V*/) const { return false; }
556 
557   bool compare(const GenericOptionValue & /*V*/) const override {
558     return false;
559   }
560 
561 protected:
562   ~OptionValueBase() = default;
563 };
564 
565 // Simple copy of the option value.
566 template <class DataType> class OptionValueCopy : public GenericOptionValue {
567   DataType Value;
568   bool Valid = false;
569 
570 protected:
571   OptionValueCopy(const OptionValueCopy&) = default;
572   OptionValueCopy &operator=(const OptionValueCopy &) = default;
573   ~OptionValueCopy() = default;
574 
575 public:
576   OptionValueCopy() = default;
577 
578   bool hasValue() const { return Valid; }
579 
580   const DataType &getValue() const {
581     assert(Valid && "invalid option value");
582     return Value;
583   }
584 
585   void setValue(const DataType &V) {
586     Valid = true;
587     Value = V;
588   }
589 
590   bool compare(const DataType &V) const { return Valid && (Value != V); }
591 
592   bool compare(const GenericOptionValue &V) const override {
593     const OptionValueCopy<DataType> &VC =
594         static_cast<const OptionValueCopy<DataType> &>(V);
595     if (!VC.hasValue())
596       return false;
597     return compare(VC.getValue());
598   }
599 };
600 
601 // Non-class option values.
602 template <class DataType>
603 struct OptionValueBase<DataType, false> : OptionValueCopy<DataType> {
604   using WrapperType = DataType;
605 
606 protected:
607   OptionValueBase() = default;
608   OptionValueBase(const OptionValueBase&) = default;
609   OptionValueBase &operator=(const OptionValueBase &) = default;
610   ~OptionValueBase() = default;
611 };
612 
613 // Top-level option class.
614 template <class DataType>
615 struct OptionValue final
616     : OptionValueBase<DataType, std::is_class<DataType>::value> {
617   OptionValue() = default;
618 
619   OptionValue(const DataType &V) { this->setValue(V); }
620 
621   // Some options may take their value from a different data type.
622   template <class DT> OptionValue<DataType> &operator=(const DT &V) {
623     this->setValue(V);
624     return *this;
625   }
626 };
627 
628 // Other safe-to-copy-by-value common option types.
629 enum boolOrDefault { BOU_UNSET, BOU_TRUE, BOU_FALSE };
630 template <>
631 struct OptionValue<cl::boolOrDefault> final
632     : OptionValueCopy<cl::boolOrDefault> {
633   using WrapperType = cl::boolOrDefault;
634 
635   OptionValue() = default;
636 
637   OptionValue(const cl::boolOrDefault &V) { this->setValue(V); }
638 
639   OptionValue<cl::boolOrDefault> &operator=(const cl::boolOrDefault &V) {
640     setValue(V);
641     return *this;
642   }
643 
644 private:
645   void anchor() override;
646 };
647 
648 template <>
649 struct OptionValue<std::string> final : OptionValueCopy<std::string> {
650   using WrapperType = StringRef;
651 
652   OptionValue() = default;
653 
654   OptionValue(const std::string &V) { this->setValue(V); }
655 
656   OptionValue<std::string> &operator=(const std::string &V) {
657     setValue(V);
658     return *this;
659   }
660 
661 private:
662   void anchor() override;
663 };
664 
665 //===----------------------------------------------------------------------===//
666 // Enum valued command line option
667 //
668 
669 // This represents a single enum value, using "int" as the underlying type.
670 struct OptionEnumValue {
671   StringRef Name;
672   int Value;
673   StringRef Description;
674 };
675 
676 #define clEnumVal(ENUMVAL, DESC)                                               \
677   llvm::cl::OptionEnumValue { #ENUMVAL, int(ENUMVAL), DESC }
678 #define clEnumValN(ENUMVAL, FLAGNAME, DESC)                                    \
679   llvm::cl::OptionEnumValue { FLAGNAME, int(ENUMVAL), DESC }
680 
681 // For custom data types, allow specifying a group of values together as the
682 // values that go into the mapping that the option handler uses.
683 //
684 class ValuesClass {
685   // Use a vector instead of a map, because the lists should be short,
686   // the overhead is less, and most importantly, it keeps them in the order
687   // inserted so we can print our option out nicely.
688   SmallVector<OptionEnumValue, 4> Values;
689 
690 public:
691   ValuesClass(std::initializer_list<OptionEnumValue> Options)
692       : Values(Options) {}
693 
694   template <class Opt> void apply(Opt &O) const {
695     for (const auto &Value : Values)
696       O.getParser().addLiteralOption(Value.Name, Value.Value,
697                                      Value.Description);
698   }
699 };
700 
701 /// Helper to build a ValuesClass by forwarding a variable number of arguments
702 /// as an initializer list to the ValuesClass constructor.
703 template <typename... OptsTy> ValuesClass values(OptsTy... Options) {
704   return ValuesClass({Options...});
705 }
706 
707 //===----------------------------------------------------------------------===//
708 // Parameterizable parser for different data types. By default, known data types
709 // (string, int, bool) have specialized parsers, that do what you would expect.
710 // The default parser, used for data types that are not built-in, uses a mapping
711 // table to map specific options to values, which is used, among other things,
712 // to handle enum types.
713 
714 //--------------------------------------------------
715 // This class holds all the non-generic code that we do not need replicated for
716 // every instance of the generic parser.  This also allows us to put stuff into
717 // CommandLine.cpp
718 //
719 class generic_parser_base {
720 protected:
721   class GenericOptionInfo {
722   public:
723     GenericOptionInfo(StringRef name, StringRef helpStr)
724         : Name(name), HelpStr(helpStr) {}
725     StringRef Name;
726     StringRef HelpStr;
727   };
728 
729 public:
730   generic_parser_base(Option &O) : Owner(O) {}
731 
732   virtual ~generic_parser_base() = default;
733   // Base class should have virtual-destructor
734 
735   // Virtual function implemented by generic subclass to indicate how many
736   // entries are in Values.
737   //
738   virtual unsigned getNumOptions() const = 0;
739 
740   // Return option name N.
741   virtual StringRef getOption(unsigned N) const = 0;
742 
743   // Return description N
744   virtual StringRef getDescription(unsigned N) const = 0;
745 
746   // Return the width of the option tag for printing...
747   virtual size_t getOptionWidth(const Option &O) const;
748 
749   virtual const GenericOptionValue &getOptionValue(unsigned N) const = 0;
750 
751   // Print out information about this option. The to-be-maintained width is
752   // specified.
753   //
754   virtual void printOptionInfo(const Option &O, size_t GlobalWidth) const;
755 
756   void printGenericOptionDiff(const Option &O, const GenericOptionValue &V,
757                               const GenericOptionValue &Default,
758                               size_t GlobalWidth) const;
759 
760   // Print the value of an option and it's default.
761   //
762   // Template definition ensures that the option and default have the same
763   // DataType (via the same AnyOptionValue).
764   template <class AnyOptionValue>
765   void printOptionDiff(const Option &O, const AnyOptionValue &V,
766                        const AnyOptionValue &Default,
767                        size_t GlobalWidth) const {
768     printGenericOptionDiff(O, V, Default, GlobalWidth);
769   }
770 
771   void initialize() {}
772 
773   void getExtraOptionNames(SmallVectorImpl<StringRef> &OptionNames) {
774     // If there has been no argstr specified, that means that we need to add an
775     // argument for every possible option.  This ensures that our options are
776     // vectored to us.
777     if (!Owner.hasArgStr())
778       for (unsigned i = 0, e = getNumOptions(); i != e; ++i)
779         OptionNames.push_back(getOption(i));
780   }
781 
782   enum ValueExpected getValueExpectedFlagDefault() const {
783     // If there is an ArgStr specified, then we are of the form:
784     //
785     //    -opt=O2   or   -opt O2  or  -optO2
786     //
787     // In which case, the value is required.  Otherwise if an arg str has not
788     // been specified, we are of the form:
789     //
790     //    -O2 or O2 or -la (where -l and -a are separate options)
791     //
792     // If this is the case, we cannot allow a value.
793     //
794     if (Owner.hasArgStr())
795       return ValueRequired;
796     else
797       return ValueDisallowed;
798   }
799 
800   // Return the option number corresponding to the specified
801   // argument string.  If the option is not found, getNumOptions() is returned.
802   //
803   unsigned findOption(StringRef Name);
804 
805 protected:
806   Option &Owner;
807 };
808 
809 // Default parser implementation - This implementation depends on having a
810 // mapping of recognized options to values of some sort.  In addition to this,
811 // each entry in the mapping also tracks a help message that is printed with the
812 // command line option for -help.  Because this is a simple mapping parser, the
813 // data type can be any unsupported type.
814 //
815 template <class DataType> class parser : public generic_parser_base {
816 protected:
817   class OptionInfo : public GenericOptionInfo {
818   public:
819     OptionInfo(StringRef name, DataType v, StringRef helpStr)
820         : GenericOptionInfo(name, helpStr), V(v) {}
821 
822     OptionValue<DataType> V;
823   };
824   SmallVector<OptionInfo, 8> Values;
825 
826 public:
827   parser(Option &O) : generic_parser_base(O) {}
828 
829   using parser_data_type = DataType;
830 
831   // Implement virtual functions needed by generic_parser_base
832   unsigned getNumOptions() const override { return unsigned(Values.size()); }
833   StringRef getOption(unsigned N) const override { return Values[N].Name; }
834   StringRef getDescription(unsigned N) const override {
835     return Values[N].HelpStr;
836   }
837 
838   // Return the value of option name N.
839   const GenericOptionValue &getOptionValue(unsigned N) const override {
840     return Values[N].V;
841   }
842 
843   // Return true on error.
844   bool parse(Option &O, StringRef ArgName, StringRef Arg, DataType &V) {
845     StringRef ArgVal;
846     if (Owner.hasArgStr())
847       ArgVal = Arg;
848     else
849       ArgVal = ArgName;
850 
851     for (size_t i = 0, e = Values.size(); i != e; ++i)
852       if (Values[i].Name == ArgVal) {
853         V = Values[i].V.getValue();
854         return false;
855       }
856 
857     return O.error("Cannot find option named '" + ArgVal + "'!");
858   }
859 
860   /// Add an entry to the mapping table.
861   ///
862   template <class DT>
863   void addLiteralOption(StringRef Name, const DT &V, StringRef HelpStr) {
864     assert(findOption(Name) == Values.size() && "Option already exists!");
865     OptionInfo X(Name, static_cast<DataType>(V), HelpStr);
866     Values.push_back(X);
867     AddLiteralOption(Owner, Name);
868   }
869 
870   /// Remove the specified option.
871   ///
872   void removeLiteralOption(StringRef Name) {
873     unsigned N = findOption(Name);
874     assert(N != Values.size() && "Option not found!");
875     Values.erase(Values.begin() + N);
876   }
877 };
878 
879 //--------------------------------------------------
880 // Super class of parsers to provide boilerplate code
881 //
882 class basic_parser_impl { // non-template implementation of basic_parser<t>
883 public:
884   basic_parser_impl(Option &) {}
885 
886   virtual ~basic_parser_impl() = default;
887 
888   enum ValueExpected getValueExpectedFlagDefault() const {
889     return ValueRequired;
890   }
891 
892   void getExtraOptionNames(SmallVectorImpl<StringRef> &) {}
893 
894   void initialize() {}
895 
896   // Return the width of the option tag for printing...
897   size_t getOptionWidth(const Option &O) const;
898 
899   // Print out information about this option. The to-be-maintained width is
900   // specified.
901   //
902   void printOptionInfo(const Option &O, size_t GlobalWidth) const;
903 
904   // Print a placeholder for options that don't yet support printOptionDiff().
905   void printOptionNoValue(const Option &O, size_t GlobalWidth) const;
906 
907   // Overload in subclass to provide a better default value.
908   virtual StringRef getValueName() const { return "value"; }
909 
910   // An out-of-line virtual method to provide a 'home' for this class.
911   virtual void anchor();
912 
913 protected:
914   // A helper for basic_parser::printOptionDiff.
915   void printOptionName(const Option &O, size_t GlobalWidth) const;
916 };
917 
918 // The real basic parser is just a template wrapper that provides a typedef for
919 // the provided data type.
920 //
921 template <class DataType> class basic_parser : public basic_parser_impl {
922 public:
923   using parser_data_type = DataType;
924   using OptVal = OptionValue<DataType>;
925 
926   basic_parser(Option &O) : basic_parser_impl(O) {}
927 };
928 
929 //--------------------------------------------------
930 
931 extern template class basic_parser<bool>;
932 
933 template <> class parser<bool> : public basic_parser<bool> {
934 public:
935   parser(Option &O) : basic_parser(O) {}
936 
937   // Return true on error.
938   bool parse(Option &O, StringRef ArgName, StringRef Arg, bool &Val);
939 
940   void initialize() {}
941 
942   enum ValueExpected getValueExpectedFlagDefault() const {
943     return ValueOptional;
944   }
945 
946   // Do not print =<value> at all.
947   StringRef getValueName() const override { return StringRef(); }
948 
949   void printOptionDiff(const Option &O, bool V, OptVal Default,
950                        size_t GlobalWidth) const;
951 
952   // An out-of-line virtual method to provide a 'home' for this class.
953   void anchor() override;
954 };
955 
956 //--------------------------------------------------
957 
958 extern template class basic_parser<boolOrDefault>;
959 
960 template <> class parser<boolOrDefault> : public basic_parser<boolOrDefault> {
961 public:
962   parser(Option &O) : basic_parser(O) {}
963 
964   // Return true on error.
965   bool parse(Option &O, StringRef ArgName, StringRef Arg, boolOrDefault &Val);
966 
967   enum ValueExpected getValueExpectedFlagDefault() const {
968     return ValueOptional;
969   }
970 
971   // Do not print =<value> at all.
972   StringRef getValueName() const override { return StringRef(); }
973 
974   void printOptionDiff(const Option &O, boolOrDefault V, OptVal Default,
975                        size_t GlobalWidth) const;
976 
977   // An out-of-line virtual method to provide a 'home' for this class.
978   void anchor() override;
979 };
980 
981 //--------------------------------------------------
982 
983 extern template class basic_parser<int>;
984 
985 template <> class parser<int> : public basic_parser<int> {
986 public:
987   parser(Option &O) : basic_parser(O) {}
988 
989   // Return true on error.
990   bool parse(Option &O, StringRef ArgName, StringRef Arg, int &Val);
991 
992   // Overload in subclass to provide a better default value.
993   StringRef getValueName() const override { return "int"; }
994 
995   void printOptionDiff(const Option &O, int V, OptVal Default,
996                        size_t GlobalWidth) const;
997 
998   // An out-of-line virtual method to provide a 'home' for this class.
999   void anchor() override;
1000 };
1001 
1002 //--------------------------------------------------
1003 
1004 extern template class basic_parser<long>;
1005 
1006 template <> class parser<long> final : public basic_parser<long> {
1007 public:
1008   parser(Option &O) : basic_parser(O) {}
1009 
1010   // Return true on error.
1011   bool parse(Option &O, StringRef ArgName, StringRef Arg, long &Val);
1012 
1013   // Overload in subclass to provide a better default value.
1014   StringRef getValueName() const override { return "long"; }
1015 
1016   void printOptionDiff(const Option &O, long V, OptVal Default,
1017                        size_t GlobalWidth) const;
1018 
1019   // An out-of-line virtual method to provide a 'home' for this class.
1020   void anchor() override;
1021 };
1022 
1023 //--------------------------------------------------
1024 
1025 extern template class basic_parser<long long>;
1026 
1027 template <> class parser<long long> : public basic_parser<long long> {
1028 public:
1029   parser(Option &O) : basic_parser(O) {}
1030 
1031   // Return true on error.
1032   bool parse(Option &O, StringRef ArgName, StringRef Arg, long long &Val);
1033 
1034   // Overload in subclass to provide a better default value.
1035   StringRef getValueName() const override { return "long"; }
1036 
1037   void printOptionDiff(const Option &O, long long V, OptVal Default,
1038                        size_t GlobalWidth) const;
1039 
1040   // An out-of-line virtual method to provide a 'home' for this class.
1041   void anchor() override;
1042 };
1043 
1044 //--------------------------------------------------
1045 
1046 extern template class basic_parser<unsigned>;
1047 
1048 template <> class parser<unsigned> : public basic_parser<unsigned> {
1049 public:
1050   parser(Option &O) : basic_parser(O) {}
1051 
1052   // Return true on error.
1053   bool parse(Option &O, StringRef ArgName, StringRef Arg, unsigned &Val);
1054 
1055   // Overload in subclass to provide a better default value.
1056   StringRef getValueName() const override { return "uint"; }
1057 
1058   void printOptionDiff(const Option &O, unsigned V, OptVal Default,
1059                        size_t GlobalWidth) const;
1060 
1061   // An out-of-line virtual method to provide a 'home' for this class.
1062   void anchor() override;
1063 };
1064 
1065 //--------------------------------------------------
1066 
1067 extern template class basic_parser<unsigned long>;
1068 
1069 template <>
1070 class parser<unsigned long> final : public basic_parser<unsigned long> {
1071 public:
1072   parser(Option &O) : basic_parser(O) {}
1073 
1074   // Return true on error.
1075   bool parse(Option &O, StringRef ArgName, StringRef Arg, unsigned long &Val);
1076 
1077   // Overload in subclass to provide a better default value.
1078   StringRef getValueName() const override { return "ulong"; }
1079 
1080   void printOptionDiff(const Option &O, unsigned long V, OptVal Default,
1081                        size_t GlobalWidth) const;
1082 
1083   // An out-of-line virtual method to provide a 'home' for this class.
1084   void anchor() override;
1085 };
1086 
1087 //--------------------------------------------------
1088 
1089 extern template class basic_parser<unsigned long long>;
1090 
1091 template <>
1092 class parser<unsigned long long> : public basic_parser<unsigned long long> {
1093 public:
1094   parser(Option &O) : basic_parser(O) {}
1095 
1096   // Return true on error.
1097   bool parse(Option &O, StringRef ArgName, StringRef Arg,
1098              unsigned long long &Val);
1099 
1100   // Overload in subclass to provide a better default value.
1101   StringRef getValueName() const override { return "ulong"; }
1102 
1103   void printOptionDiff(const Option &O, unsigned long long V, OptVal Default,
1104                        size_t GlobalWidth) const;
1105 
1106   // An out-of-line virtual method to provide a 'home' for this class.
1107   void anchor() override;
1108 };
1109 
1110 //--------------------------------------------------
1111 
1112 extern template class basic_parser<double>;
1113 
1114 template <> class parser<double> : public basic_parser<double> {
1115 public:
1116   parser(Option &O) : basic_parser(O) {}
1117 
1118   // Return true on error.
1119   bool parse(Option &O, StringRef ArgName, StringRef Arg, double &Val);
1120 
1121   // Overload in subclass to provide a better default value.
1122   StringRef getValueName() const override { return "number"; }
1123 
1124   void printOptionDiff(const Option &O, double V, OptVal Default,
1125                        size_t GlobalWidth) const;
1126 
1127   // An out-of-line virtual method to provide a 'home' for this class.
1128   void anchor() override;
1129 };
1130 
1131 //--------------------------------------------------
1132 
1133 extern template class basic_parser<float>;
1134 
1135 template <> class parser<float> : public basic_parser<float> {
1136 public:
1137   parser(Option &O) : basic_parser(O) {}
1138 
1139   // Return true on error.
1140   bool parse(Option &O, StringRef ArgName, StringRef Arg, float &Val);
1141 
1142   // Overload in subclass to provide a better default value.
1143   StringRef getValueName() const override { return "number"; }
1144 
1145   void printOptionDiff(const Option &O, float V, OptVal Default,
1146                        size_t GlobalWidth) const;
1147 
1148   // An out-of-line virtual method to provide a 'home' for this class.
1149   void anchor() override;
1150 };
1151 
1152 //--------------------------------------------------
1153 
1154 extern template class basic_parser<std::string>;
1155 
1156 template <> class parser<std::string> : public basic_parser<std::string> {
1157 public:
1158   parser(Option &O) : basic_parser(O) {}
1159 
1160   // Return true on error.
1161   bool parse(Option &, StringRef, StringRef Arg, std::string &Value) {
1162     Value = Arg.str();
1163     return false;
1164   }
1165 
1166   // Overload in subclass to provide a better default value.
1167   StringRef getValueName() const override { return "string"; }
1168 
1169   void printOptionDiff(const Option &O, StringRef V, const OptVal &Default,
1170                        size_t GlobalWidth) const;
1171 
1172   // An out-of-line virtual method to provide a 'home' for this class.
1173   void anchor() override;
1174 };
1175 
1176 //--------------------------------------------------
1177 
1178 extern template class basic_parser<char>;
1179 
1180 template <> class parser<char> : public basic_parser<char> {
1181 public:
1182   parser(Option &O) : basic_parser(O) {}
1183 
1184   // Return true on error.
1185   bool parse(Option &, StringRef, StringRef Arg, char &Value) {
1186     Value = Arg[0];
1187     return false;
1188   }
1189 
1190   // Overload in subclass to provide a better default value.
1191   StringRef getValueName() const override { return "char"; }
1192 
1193   void printOptionDiff(const Option &O, char V, OptVal Default,
1194                        size_t GlobalWidth) const;
1195 
1196   // An out-of-line virtual method to provide a 'home' for this class.
1197   void anchor() override;
1198 };
1199 
1200 //--------------------------------------------------
1201 // This collection of wrappers is the intermediary between class opt and class
1202 // parser to handle all the template nastiness.
1203 
1204 // This overloaded function is selected by the generic parser.
1205 template <class ParserClass, class DT>
1206 void printOptionDiff(const Option &O, const generic_parser_base &P, const DT &V,
1207                      const OptionValue<DT> &Default, size_t GlobalWidth) {
1208   OptionValue<DT> OV = V;
1209   P.printOptionDiff(O, OV, Default, GlobalWidth);
1210 }
1211 
1212 // This is instantiated for basic parsers when the parsed value has a different
1213 // type than the option value. e.g. HelpPrinter.
1214 template <class ParserDT, class ValDT> struct OptionDiffPrinter {
1215   void print(const Option &O, const parser<ParserDT> &P, const ValDT & /*V*/,
1216              const OptionValue<ValDT> & /*Default*/, size_t GlobalWidth) {
1217     P.printOptionNoValue(O, GlobalWidth);
1218   }
1219 };
1220 
1221 // This is instantiated for basic parsers when the parsed value has the same
1222 // type as the option value.
1223 template <class DT> struct OptionDiffPrinter<DT, DT> {
1224   void print(const Option &O, const parser<DT> &P, const DT &V,
1225              const OptionValue<DT> &Default, size_t GlobalWidth) {
1226     P.printOptionDiff(O, V, Default, GlobalWidth);
1227   }
1228 };
1229 
1230 // This overloaded function is selected by the basic parser, which may parse a
1231 // different type than the option type.
1232 template <class ParserClass, class ValDT>
1233 void printOptionDiff(
1234     const Option &O,
1235     const basic_parser<typename ParserClass::parser_data_type> &P,
1236     const ValDT &V, const OptionValue<ValDT> &Default, size_t GlobalWidth) {
1237 
1238   OptionDiffPrinter<typename ParserClass::parser_data_type, ValDT> printer;
1239   printer.print(O, static_cast<const ParserClass &>(P), V, Default,
1240                 GlobalWidth);
1241 }
1242 
1243 //===----------------------------------------------------------------------===//
1244 // This class is used because we must use partial specialization to handle
1245 // literal string arguments specially (const char* does not correctly respond to
1246 // the apply method). Because the syntax to use this is a pain, we have the
1247 // 'apply' method below to handle the nastiness...
1248 //
1249 template <class Mod> struct applicator {
1250   template <class Opt> static void opt(const Mod &M, Opt &O) { M.apply(O); }
1251 };
1252 
1253 // Handle const char* as a special case...
1254 template <unsigned n> struct applicator<char[n]> {
1255   template <class Opt> static void opt(StringRef Str, Opt &O) {
1256     O.setArgStr(Str);
1257   }
1258 };
1259 template <unsigned n> struct applicator<const char[n]> {
1260   template <class Opt> static void opt(StringRef Str, Opt &O) {
1261     O.setArgStr(Str);
1262   }
1263 };
1264 template <> struct applicator<StringRef > {
1265   template <class Opt> static void opt(StringRef Str, Opt &O) {
1266     O.setArgStr(Str);
1267   }
1268 };
1269 
1270 template <> struct applicator<NumOccurrencesFlag> {
1271   static void opt(NumOccurrencesFlag N, Option &O) {
1272     O.setNumOccurrencesFlag(N);
1273   }
1274 };
1275 
1276 template <> struct applicator<ValueExpected> {
1277   static void opt(ValueExpected VE, Option &O) { O.setValueExpectedFlag(VE); }
1278 };
1279 
1280 template <> struct applicator<OptionHidden> {
1281   static void opt(OptionHidden OH, Option &O) { O.setHiddenFlag(OH); }
1282 };
1283 
1284 template <> struct applicator<FormattingFlags> {
1285   static void opt(FormattingFlags FF, Option &O) { O.setFormattingFlag(FF); }
1286 };
1287 
1288 template <> struct applicator<MiscFlags> {
1289   static void opt(MiscFlags MF, Option &O) {
1290     assert((MF != Grouping || O.ArgStr.size() == 1) &&
1291            "cl::Grouping can only apply to single character Options.");
1292     O.setMiscFlag(MF);
1293   }
1294 };
1295 
1296 // Apply modifiers to an option in a type safe way.
1297 template <class Opt, class Mod, class... Mods>
1298 void apply(Opt *O, const Mod &M, const Mods &... Ms) {
1299   applicator<Mod>::opt(M, *O);
1300   apply(O, Ms...);
1301 }
1302 
1303 template <class Opt, class Mod> void apply(Opt *O, const Mod &M) {
1304   applicator<Mod>::opt(M, *O);
1305 }
1306 
1307 //===----------------------------------------------------------------------===//
1308 // Default storage class definition: external storage.  This implementation
1309 // assumes the user will specify a variable to store the data into with the
1310 // cl::location(x) modifier.
1311 //
1312 template <class DataType, bool ExternalStorage, bool isClass>
1313 class opt_storage {
1314   DataType *Location = nullptr; // Where to store the object...
1315   OptionValue<DataType> Default;
1316 
1317   void check_location() const {
1318     assert(Location && "cl::location(...) not specified for a command "
1319                        "line option with external storage, "
1320                        "or cl::init specified before cl::location()!!");
1321   }
1322 
1323 public:
1324   opt_storage() = default;
1325 
1326   bool setLocation(Option &O, DataType &L) {
1327     if (Location)
1328       return O.error("cl::location(x) specified more than once!");
1329     Location = &L;
1330     Default = L;
1331     return false;
1332   }
1333 
1334   template <class T> void setValue(const T &V, bool initial = false) {
1335     check_location();
1336     *Location = V;
1337     if (initial)
1338       Default = V;
1339   }
1340 
1341   DataType &getValue() {
1342     check_location();
1343     return *Location;
1344   }
1345   const DataType &getValue() const {
1346     check_location();
1347     return *Location;
1348   }
1349 
1350   operator DataType() const { return this->getValue(); }
1351 
1352   const OptionValue<DataType> &getDefault() const { return Default; }
1353 };
1354 
1355 // Define how to hold a class type object, such as a string.  Since we can
1356 // inherit from a class, we do so.  This makes us exactly compatible with the
1357 // object in all cases that it is used.
1358 //
1359 template <class DataType>
1360 class opt_storage<DataType, false, true> : public DataType {
1361 public:
1362   OptionValue<DataType> Default;
1363 
1364   template <class T> void setValue(const T &V, bool initial = false) {
1365     DataType::operator=(V);
1366     if (initial)
1367       Default = V;
1368   }
1369 
1370   DataType &getValue() { return *this; }
1371   const DataType &getValue() const { return *this; }
1372 
1373   const OptionValue<DataType> &getDefault() const { return Default; }
1374 };
1375 
1376 // Define a partial specialization to handle things we cannot inherit from.  In
1377 // this case, we store an instance through containment, and overload operators
1378 // to get at the value.
1379 //
1380 template <class DataType> class opt_storage<DataType, false, false> {
1381 public:
1382   DataType Value;
1383   OptionValue<DataType> Default;
1384 
1385   // Make sure we initialize the value with the default constructor for the
1386   // type.
1387   opt_storage() : Value(DataType()), Default() {}
1388 
1389   template <class T> void setValue(const T &V, bool initial = false) {
1390     Value = V;
1391     if (initial)
1392       Default = V;
1393   }
1394   DataType &getValue() { return Value; }
1395   DataType getValue() const { return Value; }
1396 
1397   const OptionValue<DataType> &getDefault() const { return Default; }
1398 
1399   operator DataType() const { return getValue(); }
1400 
1401   // If the datatype is a pointer, support -> on it.
1402   DataType operator->() const { return Value; }
1403 };
1404 
1405 //===----------------------------------------------------------------------===//
1406 // A scalar command line option.
1407 //
1408 template <class DataType, bool ExternalStorage = false,
1409           class ParserClass = parser<DataType>>
1410 class opt : public Option,
1411             public opt_storage<DataType, ExternalStorage,
1412                                std::is_class<DataType>::value> {
1413   ParserClass Parser;
1414 
1415   bool handleOccurrence(unsigned pos, StringRef ArgName,
1416                         StringRef Arg) override {
1417     typename ParserClass::parser_data_type Val =
1418         typename ParserClass::parser_data_type();
1419     if (Parser.parse(*this, ArgName, Arg, Val))
1420       return true; // Parse error!
1421     this->setValue(Val);
1422     this->setPosition(pos);
1423     Callback(Val);
1424     return false;
1425   }
1426 
1427   enum ValueExpected getValueExpectedFlagDefault() const override {
1428     return Parser.getValueExpectedFlagDefault();
1429   }
1430 
1431   void getExtraOptionNames(SmallVectorImpl<StringRef> &OptionNames) override {
1432     return Parser.getExtraOptionNames(OptionNames);
1433   }
1434 
1435   // Forward printing stuff to the parser...
1436   size_t getOptionWidth() const override {
1437     return Parser.getOptionWidth(*this);
1438   }
1439 
1440   void printOptionInfo(size_t GlobalWidth) const override {
1441     Parser.printOptionInfo(*this, GlobalWidth);
1442   }
1443 
1444   void printOptionValue(size_t GlobalWidth, bool Force) const override {
1445     if (Force || this->getDefault().compare(this->getValue())) {
1446       cl::printOptionDiff<ParserClass>(*this, Parser, this->getValue(),
1447                                        this->getDefault(), GlobalWidth);
1448     }
1449   }
1450 
1451   template <class T,
1452             class = std::enable_if_t<std::is_assignable<T &, T>::value>>
1453   void setDefaultImpl() {
1454     const OptionValue<DataType> &V = this->getDefault();
1455     if (V.hasValue())
1456       this->setValue(V.getValue());
1457     else
1458       this->setValue(T());
1459   }
1460 
1461   template <class T,
1462             class = std::enable_if_t<!std::is_assignable<T &, T>::value>>
1463   void setDefaultImpl(...) {}
1464 
1465   void setDefault() override { setDefaultImpl<DataType>(); }
1466 
1467   void done() {
1468     addArgument();
1469     Parser.initialize();
1470   }
1471 
1472 public:
1473   // Command line options should not be copyable
1474   opt(const opt &) = delete;
1475   opt &operator=(const opt &) = delete;
1476 
1477   // setInitialValue - Used by the cl::init modifier...
1478   void setInitialValue(const DataType &V) { this->setValue(V, true); }
1479 
1480   ParserClass &getParser() { return Parser; }
1481 
1482   template <class T> DataType &operator=(const T &Val) {
1483     this->setValue(Val);
1484     Callback(Val);
1485     return this->getValue();
1486   }
1487 
1488   template <class... Mods>
1489   explicit opt(const Mods &... Ms)
1490       : Option(llvm::cl::Optional, NotHidden), Parser(*this) {
1491     apply(this, Ms...);
1492     done();
1493   }
1494 
1495   void setCallback(
1496       std::function<void(const typename ParserClass::parser_data_type &)> CB) {
1497     Callback = CB;
1498   }
1499 
1500   std::function<void(const typename ParserClass::parser_data_type &)> Callback =
1501       [](const typename ParserClass::parser_data_type &) {};
1502 };
1503 
1504 extern template class opt<unsigned>;
1505 extern template class opt<int>;
1506 extern template class opt<std::string>;
1507 extern template class opt<char>;
1508 extern template class opt<bool>;
1509 
1510 //===----------------------------------------------------------------------===//
1511 // Default storage class definition: external storage.  This implementation
1512 // assumes the user will specify a variable to store the data into with the
1513 // cl::location(x) modifier.
1514 //
1515 template <class DataType, class StorageClass> class list_storage {
1516   StorageClass *Location = nullptr; // Where to store the object...
1517   std::vector<OptionValue<DataType>> Default =
1518       std::vector<OptionValue<DataType>>();
1519   bool DefaultAssigned = false;
1520 
1521 public:
1522   list_storage() = default;
1523 
1524   void clear() {}
1525 
1526   bool setLocation(Option &O, StorageClass &L) {
1527     if (Location)
1528       return O.error("cl::location(x) specified more than once!");
1529     Location = &L;
1530     return false;
1531   }
1532 
1533   template <class T> void addValue(const T &V, bool initial = false) {
1534     assert(Location != nullptr &&
1535            "cl::location(...) not specified for a command "
1536            "line option with external storage!");
1537     Location->push_back(V);
1538     if (initial)
1539       Default.push_back(V);
1540   }
1541 
1542   const std::vector<OptionValue<DataType>> &getDefault() const {
1543     return Default;
1544   }
1545 
1546   void assignDefault() { DefaultAssigned = true; }
1547   void overwriteDefault() { DefaultAssigned = false; }
1548   bool isDefaultAssigned() { return DefaultAssigned; }
1549 };
1550 
1551 // Define how to hold a class type object, such as a string.
1552 // Originally this code inherited from std::vector. In transitioning to a new
1553 // API for command line options we should change this. The new implementation
1554 // of this list_storage specialization implements the minimum subset of the
1555 // std::vector API required for all the current clients.
1556 //
1557 // FIXME: Reduce this API to a more narrow subset of std::vector
1558 //
1559 template <class DataType> class list_storage<DataType, bool> {
1560   std::vector<DataType> Storage;
1561   std::vector<OptionValue<DataType>> Default;
1562   bool DefaultAssigned = false;
1563 
1564 public:
1565   using iterator = typename std::vector<DataType>::iterator;
1566 
1567   iterator begin() { return Storage.begin(); }
1568   iterator end() { return Storage.end(); }
1569 
1570   using const_iterator = typename std::vector<DataType>::const_iterator;
1571 
1572   const_iterator begin() const { return Storage.begin(); }
1573   const_iterator end() const { return Storage.end(); }
1574 
1575   using size_type = typename std::vector<DataType>::size_type;
1576 
1577   size_type size() const { return Storage.size(); }
1578 
1579   bool empty() const { return Storage.empty(); }
1580 
1581   void push_back(const DataType &value) { Storage.push_back(value); }
1582   void push_back(DataType &&value) { Storage.push_back(value); }
1583 
1584   using reference = typename std::vector<DataType>::reference;
1585   using const_reference = typename std::vector<DataType>::const_reference;
1586 
1587   reference operator[](size_type pos) { return Storage[pos]; }
1588   const_reference operator[](size_type pos) const { return Storage[pos]; }
1589 
1590   void clear() {
1591     Storage.clear();
1592   }
1593 
1594   iterator erase(const_iterator pos) { return Storage.erase(pos); }
1595   iterator erase(const_iterator first, const_iterator last) {
1596     return Storage.erase(first, last);
1597   }
1598 
1599   iterator erase(iterator pos) { return Storage.erase(pos); }
1600   iterator erase(iterator first, iterator last) {
1601     return Storage.erase(first, last);
1602   }
1603 
1604   iterator insert(const_iterator pos, const DataType &value) {
1605     return Storage.insert(pos, value);
1606   }
1607   iterator insert(const_iterator pos, DataType &&value) {
1608     return Storage.insert(pos, value);
1609   }
1610 
1611   iterator insert(iterator pos, const DataType &value) {
1612     return Storage.insert(pos, value);
1613   }
1614   iterator insert(iterator pos, DataType &&value) {
1615     return Storage.insert(pos, value);
1616   }
1617 
1618   reference front() { return Storage.front(); }
1619   const_reference front() const { return Storage.front(); }
1620 
1621   operator std::vector<DataType> &() { return Storage; }
1622   operator ArrayRef<DataType>() const { return Storage; }
1623   std::vector<DataType> *operator&() { return &Storage; }
1624   const std::vector<DataType> *operator&() const { return &Storage; }
1625 
1626   template <class T> void addValue(const T &V, bool initial = false) {
1627     Storage.push_back(V);
1628     if (initial)
1629       Default.push_back(OptionValue<DataType>(V));
1630   }
1631 
1632   const std::vector<OptionValue<DataType>> &getDefault() const {
1633     return Default;
1634   }
1635 
1636   void assignDefault() { DefaultAssigned = true; }
1637   void overwriteDefault() { DefaultAssigned = false; }
1638   bool isDefaultAssigned() { return DefaultAssigned; }
1639 };
1640 
1641 //===----------------------------------------------------------------------===//
1642 // A list of command line options.
1643 //
1644 template <class DataType, class StorageClass = bool,
1645           class ParserClass = parser<DataType>>
1646 class list : public Option, public list_storage<DataType, StorageClass> {
1647   std::vector<unsigned> Positions;
1648   ParserClass Parser;
1649 
1650   enum ValueExpected getValueExpectedFlagDefault() const override {
1651     return Parser.getValueExpectedFlagDefault();
1652   }
1653 
1654   void getExtraOptionNames(SmallVectorImpl<StringRef> &OptionNames) override {
1655     return Parser.getExtraOptionNames(OptionNames);
1656   }
1657 
1658   bool handleOccurrence(unsigned pos, StringRef ArgName,
1659                         StringRef Arg) override {
1660     typename ParserClass::parser_data_type Val =
1661         typename ParserClass::parser_data_type();
1662     if (list_storage<DataType, StorageClass>::isDefaultAssigned()) {
1663       clear();
1664       list_storage<DataType, StorageClass>::overwriteDefault();
1665     }
1666     if (Parser.parse(*this, ArgName, Arg, Val))
1667       return true; // Parse Error!
1668     list_storage<DataType, StorageClass>::addValue(Val);
1669     setPosition(pos);
1670     Positions.push_back(pos);
1671     Callback(Val);
1672     return false;
1673   }
1674 
1675   // Forward printing stuff to the parser...
1676   size_t getOptionWidth() const override {
1677     return Parser.getOptionWidth(*this);
1678   }
1679 
1680   void printOptionInfo(size_t GlobalWidth) const override {
1681     Parser.printOptionInfo(*this, GlobalWidth);
1682   }
1683 
1684   // Unimplemented: list options don't currently store their default value.
1685   void printOptionValue(size_t /*GlobalWidth*/, bool /*Force*/) const override {
1686   }
1687 
1688   void setDefault() override {
1689     Positions.clear();
1690     list_storage<DataType, StorageClass>::clear();
1691     for (auto &Val : list_storage<DataType, StorageClass>::getDefault())
1692       list_storage<DataType, StorageClass>::addValue(Val.getValue());
1693   }
1694 
1695   void done() {
1696     addArgument();
1697     Parser.initialize();
1698   }
1699 
1700 public:
1701   // Command line options should not be copyable
1702   list(const list &) = delete;
1703   list &operator=(const list &) = delete;
1704 
1705   ParserClass &getParser() { return Parser; }
1706 
1707   unsigned getPosition(unsigned optnum) const {
1708     assert(optnum < this->size() && "Invalid option index");
1709     return Positions[optnum];
1710   }
1711 
1712   void clear() {
1713     Positions.clear();
1714     list_storage<DataType, StorageClass>::clear();
1715   }
1716 
1717   // setInitialValues - Used by the cl::list_init modifier...
1718   void setInitialValues(ArrayRef<DataType> Vs) {
1719     assert(!(list_storage<DataType, StorageClass>::isDefaultAssigned()) &&
1720            "Cannot have two default values");
1721     list_storage<DataType, StorageClass>::assignDefault();
1722     for (auto &Val : Vs)
1723       list_storage<DataType, StorageClass>::addValue(Val, true);
1724   }
1725 
1726   void setNumAdditionalVals(unsigned n) { Option::setNumAdditionalVals(n); }
1727 
1728   template <class... Mods>
1729   explicit list(const Mods &... Ms)
1730       : Option(ZeroOrMore, NotHidden), Parser(*this) {
1731     apply(this, Ms...);
1732     done();
1733   }
1734 
1735   void setCallback(
1736       std::function<void(const typename ParserClass::parser_data_type &)> CB) {
1737     Callback = CB;
1738   }
1739 
1740   std::function<void(const typename ParserClass::parser_data_type &)> Callback =
1741       [](const typename ParserClass::parser_data_type &) {};
1742 };
1743 
1744 // Modifier to set the number of additional values.
1745 struct multi_val {
1746   unsigned AdditionalVals;
1747   explicit multi_val(unsigned N) : AdditionalVals(N) {}
1748 
1749   template <typename D, typename S, typename P>
1750   void apply(list<D, S, P> &L) const {
1751     L.setNumAdditionalVals(AdditionalVals);
1752   }
1753 };
1754 
1755 //===----------------------------------------------------------------------===//
1756 // Default storage class definition: external storage.  This implementation
1757 // assumes the user will specify a variable to store the data into with the
1758 // cl::location(x) modifier.
1759 //
1760 template <class DataType, class StorageClass> class bits_storage {
1761   unsigned *Location = nullptr; // Where to store the bits...
1762 
1763   template <class T> static unsigned Bit(const T &V) {
1764     unsigned BitPos = static_cast<unsigned>(V);
1765     assert(BitPos < sizeof(unsigned) * CHAR_BIT &&
1766            "enum exceeds width of bit vector!");
1767     return 1 << BitPos;
1768   }
1769 
1770 public:
1771   bits_storage() = default;
1772 
1773   bool setLocation(Option &O, unsigned &L) {
1774     if (Location)
1775       return O.error("cl::location(x) specified more than once!");
1776     Location = &L;
1777     return false;
1778   }
1779 
1780   template <class T> void addValue(const T &V) {
1781     assert(Location != nullptr &&
1782            "cl::location(...) not specified for a command "
1783            "line option with external storage!");
1784     *Location |= Bit(V);
1785   }
1786 
1787   unsigned getBits() { return *Location; }
1788 
1789   void clear() {
1790     if (Location)
1791       *Location = 0;
1792   }
1793 
1794   template <class T> bool isSet(const T &V) {
1795     return (*Location & Bit(V)) != 0;
1796   }
1797 };
1798 
1799 // Define how to hold bits.  Since we can inherit from a class, we do so.
1800 // This makes us exactly compatible with the bits in all cases that it is used.
1801 //
1802 template <class DataType> class bits_storage<DataType, bool> {
1803   unsigned Bits{0}; // Where to store the bits...
1804 
1805   template <class T> static unsigned Bit(const T &V) {
1806     unsigned BitPos = static_cast<unsigned>(V);
1807     assert(BitPos < sizeof(unsigned) * CHAR_BIT &&
1808            "enum exceeds width of bit vector!");
1809     return 1 << BitPos;
1810   }
1811 
1812 public:
1813   template <class T> void addValue(const T &V) { Bits |= Bit(V); }
1814 
1815   unsigned getBits() { return Bits; }
1816 
1817   void clear() { Bits = 0; }
1818 
1819   template <class T> bool isSet(const T &V) { return (Bits & Bit(V)) != 0; }
1820 };
1821 
1822 //===----------------------------------------------------------------------===//
1823 // A bit vector of command options.
1824 //
1825 template <class DataType, class Storage = bool,
1826           class ParserClass = parser<DataType>>
1827 class bits : public Option, public bits_storage<DataType, Storage> {
1828   std::vector<unsigned> Positions;
1829   ParserClass Parser;
1830 
1831   enum ValueExpected getValueExpectedFlagDefault() const override {
1832     return Parser.getValueExpectedFlagDefault();
1833   }
1834 
1835   void getExtraOptionNames(SmallVectorImpl<StringRef> &OptionNames) override {
1836     return Parser.getExtraOptionNames(OptionNames);
1837   }
1838 
1839   bool handleOccurrence(unsigned pos, StringRef ArgName,
1840                         StringRef Arg) override {
1841     typename ParserClass::parser_data_type Val =
1842         typename ParserClass::parser_data_type();
1843     if (Parser.parse(*this, ArgName, Arg, Val))
1844       return true; // Parse Error!
1845     this->addValue(Val);
1846     setPosition(pos);
1847     Positions.push_back(pos);
1848     Callback(Val);
1849     return false;
1850   }
1851 
1852   // Forward printing stuff to the parser...
1853   size_t getOptionWidth() const override {
1854     return Parser.getOptionWidth(*this);
1855   }
1856 
1857   void printOptionInfo(size_t GlobalWidth) const override {
1858     Parser.printOptionInfo(*this, GlobalWidth);
1859   }
1860 
1861   // Unimplemented: bits options don't currently store their default values.
1862   void printOptionValue(size_t /*GlobalWidth*/, bool /*Force*/) const override {
1863   }
1864 
1865   void setDefault() override { bits_storage<DataType, Storage>::clear(); }
1866 
1867   void done() {
1868     addArgument();
1869     Parser.initialize();
1870   }
1871 
1872 public:
1873   // Command line options should not be copyable
1874   bits(const bits &) = delete;
1875   bits &operator=(const bits &) = delete;
1876 
1877   ParserClass &getParser() { return Parser; }
1878 
1879   unsigned getPosition(unsigned optnum) const {
1880     assert(optnum < this->size() && "Invalid option index");
1881     return Positions[optnum];
1882   }
1883 
1884   template <class... Mods>
1885   explicit bits(const Mods &... Ms)
1886       : Option(ZeroOrMore, NotHidden), Parser(*this) {
1887     apply(this, Ms...);
1888     done();
1889   }
1890 
1891   void setCallback(
1892       std::function<void(const typename ParserClass::parser_data_type &)> CB) {
1893     Callback = CB;
1894   }
1895 
1896   std::function<void(const typename ParserClass::parser_data_type &)> Callback =
1897       [](const typename ParserClass::parser_data_type &) {};
1898 };
1899 
1900 //===----------------------------------------------------------------------===//
1901 // Aliased command line option (alias this name to a preexisting name)
1902 //
1903 
1904 class alias : public Option {
1905   Option *AliasFor;
1906 
1907   bool handleOccurrence(unsigned pos, StringRef /*ArgName*/,
1908                         StringRef Arg) override {
1909     return AliasFor->handleOccurrence(pos, AliasFor->ArgStr, Arg);
1910   }
1911 
1912   bool addOccurrence(unsigned pos, StringRef /*ArgName*/, StringRef Value,
1913                      bool MultiArg = false) override {
1914     return AliasFor->addOccurrence(pos, AliasFor->ArgStr, Value, MultiArg);
1915   }
1916 
1917   // Handle printing stuff...
1918   size_t getOptionWidth() const override;
1919   void printOptionInfo(size_t GlobalWidth) const override;
1920 
1921   // Aliases do not need to print their values.
1922   void printOptionValue(size_t /*GlobalWidth*/, bool /*Force*/) const override {
1923   }
1924 
1925   void setDefault() override { AliasFor->setDefault(); }
1926 
1927   ValueExpected getValueExpectedFlagDefault() const override {
1928     return AliasFor->getValueExpectedFlag();
1929   }
1930 
1931   void done() {
1932     if (!hasArgStr())
1933       error("cl::alias must have argument name specified!");
1934     if (!AliasFor)
1935       error("cl::alias must have an cl::aliasopt(option) specified!");
1936     if (!Subs.empty())
1937       error("cl::alias must not have cl::sub(), aliased option's cl::sub() will be used!");
1938     Subs = AliasFor->Subs;
1939     Categories = AliasFor->Categories;
1940     addArgument();
1941   }
1942 
1943 public:
1944   // Command line options should not be copyable
1945   alias(const alias &) = delete;
1946   alias &operator=(const alias &) = delete;
1947 
1948   void setAliasFor(Option &O) {
1949     if (AliasFor)
1950       error("cl::alias must only have one cl::aliasopt(...) specified!");
1951     AliasFor = &O;
1952   }
1953 
1954   template <class... Mods>
1955   explicit alias(const Mods &... Ms)
1956       : Option(Optional, Hidden), AliasFor(nullptr) {
1957     apply(this, Ms...);
1958     done();
1959   }
1960 };
1961 
1962 // Modifier to set the option an alias aliases.
1963 struct aliasopt {
1964   Option &Opt;
1965 
1966   explicit aliasopt(Option &O) : Opt(O) {}
1967 
1968   void apply(alias &A) const { A.setAliasFor(Opt); }
1969 };
1970 
1971 // Provide additional help at the end of the normal help output. All occurrences
1972 // of cl::extrahelp will be accumulated and printed to stderr at the end of the
1973 // regular help, just before exit is called.
1974 struct extrahelp {
1975   StringRef morehelp;
1976 
1977   explicit extrahelp(StringRef help);
1978 };
1979 
1980 void PrintVersionMessage();
1981 
1982 /// This function just prints the help message, exactly the same way as if the
1983 /// -help or -help-hidden option had been given on the command line.
1984 ///
1985 /// \param Hidden if true will print hidden options
1986 /// \param Categorized if true print options in categories
1987 void PrintHelpMessage(bool Hidden = false, bool Categorized = false);
1988 
1989 //===----------------------------------------------------------------------===//
1990 // Public interface for accessing registered options.
1991 //
1992 
1993 /// Use this to get a StringMap to all registered named options
1994 /// (e.g. -help).
1995 ///
1996 /// \return A reference to the StringMap used by the cl APIs to parse options.
1997 ///
1998 /// Access to unnamed arguments (i.e. positional) are not provided because
1999 /// it is expected that the client already has access to these.
2000 ///
2001 /// Typical usage:
2002 /// \code
2003 /// main(int argc,char* argv[]) {
2004 /// StringMap<llvm::cl::Option*> &opts = llvm::cl::getRegisteredOptions();
2005 /// assert(opts.count("help") == 1)
2006 /// opts["help"]->setDescription("Show alphabetical help information")
2007 /// // More code
2008 /// llvm::cl::ParseCommandLineOptions(argc,argv);
2009 /// //More code
2010 /// }
2011 /// \endcode
2012 ///
2013 /// This interface is useful for modifying options in libraries that are out of
2014 /// the control of the client. The options should be modified before calling
2015 /// llvm::cl::ParseCommandLineOptions().
2016 ///
2017 /// Hopefully this API can be deprecated soon. Any situation where options need
2018 /// to be modified by tools or libraries should be handled by sane APIs rather
2019 /// than just handing around a global list.
2020 StringMap<Option *> &
2021 getRegisteredOptions(SubCommand &Sub = SubCommand::getTopLevel());
2022 
2023 /// Use this to get all registered SubCommands from the provided parser.
2024 ///
2025 /// \return A range of all SubCommand pointers registered with the parser.
2026 ///
2027 /// Typical usage:
2028 /// \code
2029 /// main(int argc, char* argv[]) {
2030 ///   llvm::cl::ParseCommandLineOptions(argc, argv);
2031 ///   for (auto* S : llvm::cl::getRegisteredSubcommands()) {
2032 ///     if (*S) {
2033 ///       std::cout << "Executing subcommand: " << S->getName() << std::endl;
2034 ///       // Execute some function based on the name...
2035 ///     }
2036 ///   }
2037 /// }
2038 /// \endcode
2039 ///
2040 /// This interface is useful for defining subcommands in libraries and
2041 /// the dispatch from a single point (like in the main function).
2042 iterator_range<typename SmallPtrSet<SubCommand *, 4>::iterator>
2043 getRegisteredSubcommands();
2044 
2045 //===----------------------------------------------------------------------===//
2046 // Standalone command line processing utilities.
2047 //
2048 
2049 /// Tokenizes a command line that can contain escapes and quotes.
2050 //
2051 /// The quoting rules match those used by GCC and other tools that use
2052 /// libiberty's buildargv() or expandargv() utilities, and do not match bash.
2053 /// They differ from buildargv() on treatment of backslashes that do not escape
2054 /// a special character to make it possible to accept most Windows file paths.
2055 ///
2056 /// \param [in] Source The string to be split on whitespace with quotes.
2057 /// \param [in] Saver Delegates back to the caller for saving parsed strings.
2058 /// \param [in] MarkEOLs true if tokenizing a response file and you want end of
2059 /// lines and end of the response file to be marked with a nullptr string.
2060 /// \param [out] NewArgv All parsed strings are appended to NewArgv.
2061 void TokenizeGNUCommandLine(StringRef Source, StringSaver &Saver,
2062                             SmallVectorImpl<const char *> &NewArgv,
2063                             bool MarkEOLs = false);
2064 
2065 /// Tokenizes a string of Windows command line arguments, which may contain
2066 /// quotes and escaped quotes.
2067 ///
2068 /// See MSDN docs for CommandLineToArgvW for information on the quoting rules.
2069 /// http://msdn.microsoft.com/en-us/library/windows/desktop/17w5ykft(v=vs.85).aspx
2070 ///
2071 /// For handling a full Windows command line including the executable name at
2072 /// the start, see TokenizeWindowsCommandLineFull below.
2073 ///
2074 /// \param [in] Source The string to be split on whitespace with quotes.
2075 /// \param [in] Saver Delegates back to the caller for saving parsed strings.
2076 /// \param [in] MarkEOLs true if tokenizing a response file and you want end of
2077 /// lines and end of the response file to be marked with a nullptr string.
2078 /// \param [out] NewArgv All parsed strings are appended to NewArgv.
2079 void TokenizeWindowsCommandLine(StringRef Source, StringSaver &Saver,
2080                                 SmallVectorImpl<const char *> &NewArgv,
2081                                 bool MarkEOLs = false);
2082 
2083 /// Tokenizes a Windows command line while attempting to avoid copies. If no
2084 /// quoting or escaping was used, this produces substrings of the original
2085 /// string. If a token requires unquoting, it will be allocated with the
2086 /// StringSaver.
2087 void TokenizeWindowsCommandLineNoCopy(StringRef Source, StringSaver &Saver,
2088                                       SmallVectorImpl<StringRef> &NewArgv);
2089 
2090 /// Tokenizes a Windows full command line, including command name at the start.
2091 ///
2092 /// This uses the same syntax rules as TokenizeWindowsCommandLine for all but
2093 /// the first token. But the first token is expected to be parsed as the
2094 /// executable file name in the way CreateProcess would do it, rather than the
2095 /// way the C library startup code would do it: CreateProcess does not consider
2096 /// that \ is ever an escape character (because " is not a valid filename char,
2097 /// hence there's never a need to escape it to be used literally).
2098 ///
2099 /// Parameters are the same as for TokenizeWindowsCommandLine. In particular,
2100 /// if you set MarkEOLs = true, then the first word of every line will be
2101 /// parsed using the special rules for command names, making this function
2102 /// suitable for parsing a file full of commands to execute.
2103 void TokenizeWindowsCommandLineFull(StringRef Source, StringSaver &Saver,
2104                                     SmallVectorImpl<const char *> &NewArgv,
2105                                     bool MarkEOLs = false);
2106 
2107 /// String tokenization function type.  Should be compatible with either
2108 /// Windows or Unix command line tokenizers.
2109 using TokenizerCallback = void (*)(StringRef Source, StringSaver &Saver,
2110                                    SmallVectorImpl<const char *> &NewArgv,
2111                                    bool MarkEOLs);
2112 
2113 /// Tokenizes content of configuration file.
2114 ///
2115 /// \param [in] Source The string representing content of config file.
2116 /// \param [in] Saver Delegates back to the caller for saving parsed strings.
2117 /// \param [out] NewArgv All parsed strings are appended to NewArgv.
2118 /// \param [in] MarkEOLs Added for compatibility with TokenizerCallback.
2119 ///
2120 /// It works like TokenizeGNUCommandLine with ability to skip comment lines.
2121 ///
2122 void tokenizeConfigFile(StringRef Source, StringSaver &Saver,
2123                         SmallVectorImpl<const char *> &NewArgv,
2124                         bool MarkEOLs = false);
2125 
2126 /// Contains options that control response file expansion.
2127 class ExpansionContext {
2128   /// Provides persistent storage for parsed strings.
2129   StringSaver Saver;
2130 
2131   /// Tokenization strategy. Typically Unix or Windows.
2132   TokenizerCallback Tokenizer;
2133 
2134   /// File system used for all file access when running the expansion.
2135   vfs::FileSystem *FS;
2136 
2137   /// Path used to resolve relative rsp files. If empty, the file system
2138   /// current directory is used instead.
2139   StringRef CurrentDir;
2140 
2141   /// Directories used for search of config files.
2142   ArrayRef<StringRef> SearchDirs;
2143 
2144   /// True if names of nested response files must be resolved relative to
2145   /// including file.
2146   bool RelativeNames = false;
2147 
2148   /// If true, mark end of lines and the end of the response file with nullptrs
2149   /// in the Argv vector.
2150   bool MarkEOLs = false;
2151 
2152   /// If true, body of config file is expanded.
2153   bool InConfigFile = false;
2154 
2155   llvm::Error expandResponseFile(StringRef FName,
2156                                  SmallVectorImpl<const char *> &NewArgv);
2157 
2158 public:
2159   ExpansionContext(BumpPtrAllocator &A, TokenizerCallback T);
2160 
2161   ExpansionContext &setMarkEOLs(bool X) {
2162     MarkEOLs = X;
2163     return *this;
2164   }
2165 
2166   ExpansionContext &setRelativeNames(bool X) {
2167     RelativeNames = X;
2168     return *this;
2169   }
2170 
2171   ExpansionContext &setCurrentDir(StringRef X) {
2172     CurrentDir = X;
2173     return *this;
2174   }
2175 
2176   ExpansionContext &setSearchDirs(ArrayRef<StringRef> X) {
2177     SearchDirs = X;
2178     return *this;
2179   }
2180 
2181   ExpansionContext &setVFS(vfs::FileSystem *X) {
2182     FS = X;
2183     return *this;
2184   }
2185 
2186   /// Looks for the specified configuration file.
2187   ///
2188   /// \param[in]  FileName Name of the file to search for.
2189   /// \param[out] FilePath File absolute path, if it was found.
2190   /// \return True if file was found.
2191   ///
2192   /// If the specified file name contains a directory separator, it is searched
2193   /// for by its absolute path. Otherwise looks for file sequentially in
2194   /// directories specified by SearchDirs field.
2195   bool findConfigFile(StringRef FileName, SmallVectorImpl<char> &FilePath);
2196 
2197   /// Reads command line options from the given configuration file.
2198   ///
2199   /// \param [in] CfgFile Path to configuration file.
2200   /// \param [out] Argv Array to which the read options are added.
2201   /// \return true if the file was successfully read.
2202   ///
2203   /// It reads content of the specified file, tokenizes it and expands "@file"
2204   /// commands resolving file names in them relative to the directory where
2205   /// CfgFilename resides. It also expands "<CFGDIR>" to the base path of the
2206   /// current config file.
2207   Error readConfigFile(StringRef CfgFile, SmallVectorImpl<const char *> &Argv);
2208 
2209   /// Expands constructs "@file" in the provided array of arguments recursively.
2210   Error expandResponseFiles(SmallVectorImpl<const char *> &Argv);
2211 };
2212 
2213 /// A convenience helper which concatenates the options specified by the
2214 /// environment variable EnvVar and command line options, then expands
2215 /// response files recursively.
2216 /// \return true if all @files were expanded successfully or there were none.
2217 bool expandResponseFiles(int Argc, const char *const *Argv, const char *EnvVar,
2218                          SmallVectorImpl<const char *> &NewArgv);
2219 
2220 /// A convenience helper which supports the typical use case of expansion
2221 /// function call.
2222 bool ExpandResponseFiles(StringSaver &Saver, TokenizerCallback Tokenizer,
2223                          SmallVectorImpl<const char *> &Argv);
2224 
2225 /// A convenience helper which concatenates the options specified by the
2226 /// environment variable EnvVar and command line options, then expands response
2227 /// files recursively. The tokenizer is a predefined GNU or Windows one.
2228 /// \return true if all @files were expanded successfully or there were none.
2229 bool expandResponseFiles(int Argc, const char *const *Argv, const char *EnvVar,
2230                          StringSaver &Saver,
2231                          SmallVectorImpl<const char *> &NewArgv);
2232 
2233 /// Mark all options not part of this category as cl::ReallyHidden.
2234 ///
2235 /// \param Category the category of options to keep displaying
2236 ///
2237 /// Some tools (like clang-format) like to be able to hide all options that are
2238 /// not specific to the tool. This function allows a tool to specify a single
2239 /// option category to display in the -help output.
2240 void HideUnrelatedOptions(cl::OptionCategory &Category,
2241                           SubCommand &Sub = SubCommand::getTopLevel());
2242 
2243 /// Mark all options not part of the categories as cl::ReallyHidden.
2244 ///
2245 /// \param Categories the categories of options to keep displaying.
2246 ///
2247 /// Some tools (like clang-format) like to be able to hide all options that are
2248 /// not specific to the tool. This function allows a tool to specify a single
2249 /// option category to display in the -help output.
2250 void HideUnrelatedOptions(ArrayRef<const cl::OptionCategory *> Categories,
2251                           SubCommand &Sub = SubCommand::getTopLevel());
2252 
2253 /// Reset all command line options to a state that looks as if they have
2254 /// never appeared on the command line.  This is useful for being able to parse
2255 /// a command line multiple times (especially useful for writing tests).
2256 void ResetAllOptionOccurrences();
2257 
2258 /// Reset the command line parser back to its initial state.  This
2259 /// removes
2260 /// all options, categories, and subcommands and returns the parser to a state
2261 /// where no options are supported.
2262 void ResetCommandLineParser();
2263 
2264 /// Parses `Arg` into the option handler `Handler`.
2265 bool ProvidePositionalOption(Option *Handler, StringRef Arg, int i);
2266 
2267 } // end namespace cl
2268 
2269 } // end namespace llvm
2270 
2271 #endif // LLVM_SUPPORT_COMMANDLINE_H
2272