llvm/Option/OptTable.h

0001 //===- OptTable.h - Option Table --------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLVM_OPTION_OPTTABLE_H
0010 #define LLVM_OPTION_OPTTABLE_H
0011
0012 #include "llvm/ADT/ArrayRef.h"
0013 #include "llvm/ADT/SmallString.h"
0014 #include "llvm/ADT/StringRef.h"
0015 #include "llvm/ADT/StringTable.h"
0016 #include "llvm/Option/OptSpecifier.h"
0017 #include "llvm/Support/StringSaver.h"
0018 #include <cassert>
0019 #include <string>
0020 #include <vector>
0021
0022 namespace llvm {
0023
0024 class raw_ostream;
0025 template <typename Fn> class function_ref;
0026
0027 namespace opt {
0028
0029 class Arg;
0030 class ArgList;
0031 class InputArgList;
0032 class Option;
0033
0034 /// Helper for overload resolution while transitioning from
0035 /// FlagsToInclude/FlagsToExclude APIs to VisibilityMask APIs.
0036 class Visibility {
0037   unsigned Mask = ~0U;
0038
0039 public:
0040   explicit Visibility(unsigned Mask) : Mask(Mask) {}
0041   Visibility() = default;
0042
0043   operator unsigned() const { return Mask; }
0044 };
0045
0046 /// Provide access to the Option info table.
0047 ///
0048 /// The OptTable class provides a layer of indirection which allows Option
0049 /// instance to be created lazily. In the common case, only a few options will
0050 /// be needed at runtime; the OptTable class maintains enough information to
0051 /// parse command lines without instantiating Options, while letting other
0052 /// parts of the driver still use Option instances where convenient.
0053 class OptTable {
0054 public:
0055   /// Entry for a single option instance in the option data table.
0056   struct Info {
0057     unsigned PrefixesOffset;
0058     StringTable::Offset PrefixedNameOffset;
0059     const char *HelpText;
0060     // Help text for specific visibilities. A list of pairs, where each pair
0061     // is a list of visibilities and a specific help string for those
0062     // visibilities. If no help text is found in this list for the visibility of
0063     // the program, HelpText is used instead. This cannot use std::vector
0064     // because OptTable is used in constexpr contexts. Increase the array sizes
0065     // here if you need more entries and adjust the constants in
0066     // OptionParserEmitter::EmitHelpTextsForVariants.
0067     std::array<std::pair<std::array<unsigned int, 2 /*MaxVisibilityPerHelp*/>,
0068                          const char *>,
0069                1 /*MaxVisibilityHelp*/>
0070         HelpTextsForVariants;
0071     const char *MetaVar;
0072     unsigned ID;
0073     unsigned char Kind;
0074     unsigned char Param;
0075     unsigned int Flags;
0076     unsigned int Visibility;
0077     unsigned short GroupID;
0078     unsigned short AliasID;
0079     const char *AliasArgs;
0080     const char *Values;
0081
0082     bool hasNoPrefix() const { return PrefixesOffset == 0; }
0083
0084     unsigned getNumPrefixes(ArrayRef<StringTable::Offset> PrefixesTable) const {
0085       // We embed the number of prefixes in the value of the first offset.
0086       return PrefixesTable[PrefixesOffset].value();
0087     }
0088
0089     ArrayRef<StringTable::Offset>
0090     getPrefixOffsets(ArrayRef<StringTable::Offset> PrefixesTable) const {
0091       return hasNoPrefix() ? ArrayRef<StringTable::Offset>()
0092                            : PrefixesTable.slice(PrefixesOffset + 1,
0093                                                  getNumPrefixes(PrefixesTable));
0094     }
0095
0096     void appendPrefixes(const StringTable &StrTable,
0097                         ArrayRef<StringTable::Offset> PrefixesTable,
0098                         SmallVectorImpl<StringRef> &Prefixes) const {
0099       for (auto PrefixOffset : getPrefixOffsets(PrefixesTable))
0100         Prefixes.push_back(StrTable[PrefixOffset]);
0101     }
0102
0103     StringRef getPrefix(const StringTable &StrTable,
0104                         ArrayRef<StringTable::Offset> PrefixesTable,
0105                         unsigned PrefixIndex) const {
0106       return StrTable[getPrefixOffsets(PrefixesTable)[PrefixIndex]];
0107     }
0108
0109     StringRef getPrefixedName(const StringTable &StrTable) const {
0110       return StrTable[PrefixedNameOffset];
0111     }
0112
0113     StringRef getName(const StringTable &StrTable,
0114                       ArrayRef<StringTable::Offset> PrefixesTable) const {
0115       unsigned PrefixLength =
0116           hasNoPrefix() ? 0 : getPrefix(StrTable, PrefixesTable, 0).size();
0117       return getPrefixedName(StrTable).drop_front(PrefixLength);
0118     }
0119   };
0120
0121 private:
0122   // A unified string table for these options. Individual strings are stored as
0123   // null terminated C-strings at offsets within this table.
0124   const StringTable *StrTable;
0125
0126   // A table of different sets of prefixes. Each set starts with the number of
0127   // prefixes in that set followed by that many offsets into the string table
0128   // for each of the prefix strings. This is essentially a Pascal-string style
0129   // encoding.
0130   ArrayRef<StringTable::Offset> PrefixesTable;
0131
0132   /// The option information table.
0133   ArrayRef<Info> OptionInfos;
0134
0135   bool IgnoreCase;
0136   bool GroupedShortOptions = false;
0137   bool DashDashParsing = false;
0138   const char *EnvVar = nullptr;
0139
0140   unsigned InputOptionID = 0;
0141   unsigned UnknownOptionID = 0;
0142
0143 protected:
0144   /// The index of the first option which can be parsed (i.e., is not a
0145   /// special option like 'input' or 'unknown', and is not an option group).
0146   unsigned FirstSearchableIndex = 0;
0147
0148   /// The union of all option prefixes. If an argument does not begin with
0149   /// one of these, it is an input.
0150   SmallVector<StringRef> PrefixesUnion;
0151
0152   /// The union of the first element of all option prefixes.
0153   SmallString<8> PrefixChars;
0154
0155 private:
0156   const Info &getInfo(OptSpecifier Opt) const {
0157     unsigned id = Opt.getID();
0158     assert(id > 0 && id - 1 < getNumOptions() && "Invalid Option ID.");
0159     return OptionInfos[id - 1];
0160   }
0161
0162   std::unique_ptr<Arg> parseOneArgGrouped(InputArgList &Args,
0163                                           unsigned &Index) const;
0164
0165 protected:
0166   /// Initialize OptTable using Tablegen'ed OptionInfos. Child class must
0167   /// manually call \c buildPrefixChars once they are fully constructed.
0168   OptTable(const StringTable &StrTable,
0169            ArrayRef<StringTable::Offset> PrefixesTable,
0170            ArrayRef<Info> OptionInfos, bool IgnoreCase = false);
0171
0172   /// Build (or rebuild) the PrefixChars member.
0173   void buildPrefixChars();
0174
0175 public:
0176   virtual ~OptTable();
0177
0178   /// Return the string table used for option names.
0179   const StringTable &getStrTable() const { return *StrTable; }
0180
0181   /// Return the prefixes table used for option names.
0182   ArrayRef<StringTable::Offset> getPrefixesTable() const {
0183     return PrefixesTable;
0184   }
0185
0186   /// Return the total number of option classes.
0187   unsigned getNumOptions() const { return OptionInfos.size(); }
0188
0189   /// Get the given Opt's Option instance, lazily creating it
0190   /// if necessary.
0191   ///
0192   /// \return The option, or null for the INVALID option id.
0193   const Option getOption(OptSpecifier Opt) const;
0194
0195   /// Lookup the name of the given option.
0196   StringRef getOptionName(OptSpecifier id) const {
0197     return getInfo(id).getName(*StrTable, PrefixesTable);
0198   }
0199
0200   /// Lookup the prefix of the given option.
0201   StringRef getOptionPrefix(OptSpecifier id) const {
0202     const Info &I = getInfo(id);
0203     return I.hasNoPrefix() ? StringRef()
0204                            : I.getPrefix(*StrTable, PrefixesTable, 0);
0205   }
0206
0207   void appendOptionPrefixes(OptSpecifier id,
0208                             SmallVectorImpl<StringRef> &Prefixes) const {
0209     const Info &I = getInfo(id);
0210     I.appendPrefixes(*StrTable, PrefixesTable, Prefixes);
0211   }
0212
0213   /// Lookup the prefixed name of the given option.
0214   StringRef getOptionPrefixedName(OptSpecifier id) const {
0215     return getInfo(id).getPrefixedName(*StrTable);
0216   }
0217
0218   /// Get the kind of the given option.
0219   unsigned getOptionKind(OptSpecifier id) const {
0220     return getInfo(id).Kind;
0221   }
0222
0223   /// Get the group id for the given option.
0224   unsigned getOptionGroupID(OptSpecifier id) const {
0225     return getInfo(id).GroupID;
0226   }
0227
0228   /// Get the help text to use to describe this option.
0229   const char *getOptionHelpText(OptSpecifier id) const {
0230     return getOptionHelpText(id, Visibility(0));
0231   }
0232
0233   // Get the help text to use to describe this option.
0234   // If it has visibility specific help text and that visibility is in the
0235   // visibility mask, use that text instead of the generic text.
0236   const char *getOptionHelpText(OptSpecifier id,
0237                                 Visibility VisibilityMask) const {
0238     auto Info = getInfo(id);
0239     for (auto [Visibilities, Text] : Info.HelpTextsForVariants)
0240       for (auto Visibility : Visibilities)
0241         if (VisibilityMask & Visibility)
0242           return Text;
0243     return Info.HelpText;
0244   }
0245
0246   /// Get the meta-variable name to use when describing
0247   /// this options values in the help text.
0248   const char *getOptionMetaVar(OptSpecifier id) const {
0249     return getInfo(id).MetaVar;
0250   }
0251
0252   /// Specify the environment variable where initial options should be read.
0253   void setInitialOptionsFromEnvironment(const char *E) { EnvVar = E; }
0254
0255   /// Support grouped short options. e.g. -ab represents -a -b.
0256   void setGroupedShortOptions(bool Value) { GroupedShortOptions = Value; }
0257
0258   /// Set whether "--" stops option parsing and treats all subsequent arguments
0259   /// as positional. E.g. -- -a -b gives two positional inputs.
0260   void setDashDashParsing(bool Value) { DashDashParsing = Value; }
0261
0262   /// Find possible value for given flags. This is used for shell
0263   /// autocompletion.
0264   ///
0265   /// \param [in] Option - Key flag like "-stdlib=" when "-stdlib=l"
0266   /// was passed to clang.
0267   ///
0268   /// \param [in] Arg - Value which we want to autocomplete like "l"
0269   /// when "-stdlib=l" was passed to clang.
0270   ///
0271   /// \return The vector of possible values.
0272   std::vector<std::string> suggestValueCompletions(StringRef Option,
0273                                                    StringRef Arg) const;
0274
0275   /// Find flags from OptTable which starts with Cur.
0276   ///
0277   /// \param [in] Cur - String prefix that all returned flags need
0278   //  to start with.
0279   ///
0280   /// \return The vector of flags which start with Cur.
0281   std::vector<std::string> findByPrefix(StringRef Cur,
0282                                         Visibility VisibilityMask,
0283                                         unsigned int DisableFlags) const;
0284
0285   /// Find the OptTable option that most closely matches the given string.
0286   ///
0287   /// \param [in] Option - A string, such as "-stdlibs=l", that represents user
0288   /// input of an option that may not exist in the OptTable. Note that the
0289   /// string includes prefix dashes "-" as well as values "=l".
0290   /// \param [out] NearestString - The nearest option string found in the
0291   /// OptTable.
0292   /// \param [in] VisibilityMask - Only include options with any of these
0293   ///                              visibility flags set.
0294   /// \param [in] MinimumLength - Don't find options shorter than this length.
0295   /// For example, a minimum length of 3 prevents "-x" from being considered
0296   /// near to "-S".
0297   /// \param [in] MaximumDistance - Don't find options whose distance is greater
0298   /// than this value.
0299   ///
0300   /// \return The edit distance of the nearest string found.
0301   unsigned findNearest(StringRef Option, std::string &NearestString,
0302                        Visibility VisibilityMask = Visibility(),
0303                        unsigned MinimumLength = 4,
0304                        unsigned MaximumDistance = UINT_MAX) const;
0305
0306   unsigned findNearest(StringRef Option, std::string &NearestString,
0307                        unsigned FlagsToInclude, unsigned FlagsToExclude = 0,
0308                        unsigned MinimumLength = 4,
0309                        unsigned MaximumDistance = UINT_MAX) const;
0310
0311 private:
0312   unsigned
0313   internalFindNearest(StringRef Option, std::string &NearestString,
0314                       unsigned MinimumLength, unsigned MaximumDistance,
0315                       std::function<bool(const Info &)> ExcludeOption) const;
0316
0317 public:
0318   bool findExact(StringRef Option, std::string &ExactString,
0319                  Visibility VisibilityMask = Visibility()) const {
0320     return findNearest(Option, ExactString, VisibilityMask, 4, 0) == 0;
0321   }
0322
0323   bool findExact(StringRef Option, std::string &ExactString,
0324                  unsigned FlagsToInclude, unsigned FlagsToExclude = 0) const {
0325     return findNearest(Option, ExactString, FlagsToInclude, FlagsToExclude, 4,
0326                        0) == 0;
0327   }
0328
0329   /// Parse a single argument; returning the new argument and
0330   /// updating Index.
0331   ///
0332   /// \param [in,out] Index - The current parsing position in the argument
0333   /// string list; on return this will be the index of the next argument
0334   /// string to parse.
0335   /// \param [in] VisibilityMask - Only include options with any of these
0336   /// visibility flags set.
0337   ///
0338   /// \return The parsed argument, or 0 if the argument is missing values
0339   /// (in which case Index still points at the conceptual next argument string
0340   /// to parse).
0341   std::unique_ptr<Arg>
0342   ParseOneArg(const ArgList &Args, unsigned &Index,
0343               Visibility VisibilityMask = Visibility()) const;
0344
0345   std::unique_ptr<Arg> ParseOneArg(const ArgList &Args, unsigned &Index,
0346                                    unsigned FlagsToInclude,
0347                                    unsigned FlagsToExclude) const;
0348
0349 private:
0350   std::unique_ptr<Arg>
0351   internalParseOneArg(const ArgList &Args, unsigned &Index,
0352                       std::function<bool(const Option &)> ExcludeOption) const;
0353
0354 public:
0355   /// Parse an list of arguments into an InputArgList.
0356   ///
0357   /// The resulting InputArgList will reference the strings in [\p ArgBegin,
0358   /// \p ArgEnd), and their lifetime should extend past that of the returned
0359   /// InputArgList.
0360   ///
0361   /// The only error that can occur in this routine is if an argument is
0362   /// missing values; in this case \p MissingArgCount will be non-zero.
0363   ///
0364   /// \param MissingArgIndex - On error, the index of the option which could
0365   /// not be parsed.
0366   /// \param MissingArgCount - On error, the number of missing options.
0367   /// \param VisibilityMask - Only include options with any of these
0368   /// visibility flags set.
0369   /// \return An InputArgList; on error this will contain all the options
0370   /// which could be parsed.
0371   InputArgList ParseArgs(ArrayRef<const char *> Args, unsigned &MissingArgIndex,
0372                          unsigned &MissingArgCount,
0373                          Visibility VisibilityMask = Visibility()) const;
0374
0375   InputArgList ParseArgs(ArrayRef<const char *> Args, unsigned &MissingArgIndex,
0376                          unsigned &MissingArgCount, unsigned FlagsToInclude,
0377                          unsigned FlagsToExclude = 0) const;
0378
0379 private:
0380   InputArgList
0381   internalParseArgs(ArrayRef<const char *> Args, unsigned &MissingArgIndex,
0382                     unsigned &MissingArgCount,
0383                     std::function<bool(const Option &)> ExcludeOption) const;
0384
0385 public:
0386   /// A convenience helper which handles optional initial options populated from
0387   /// an environment variable, expands response files recursively and parses
0388   /// options.
0389   ///
0390   /// \param ErrorFn - Called on a formatted error message for missing arguments
0391   /// or unknown options.
0392   /// \return An InputArgList; on error this will contain all the options which
0393   /// could be parsed.
0394   InputArgList parseArgs(int Argc, char *const *Argv, OptSpecifier Unknown,
0395                          StringSaver &Saver,
0396                          std::function<void(StringRef)> ErrorFn) const;
0397
0398   /// Render the help text for an option table.
0399   ///
0400   /// \param OS - The stream to write the help text to.
0401   /// \param Usage - USAGE: Usage
0402   /// \param Title - OVERVIEW: Title
0403   /// \param VisibilityMask - Only in                 Visibility VisibilityMask,clude options with any of these
0404   ///                         visibility flags set.
0405   /// \param ShowHidden     - If true, display options marked as HelpHidden
0406   /// \param ShowAllAliases - If true, display all options including aliases
0407   ///                         that don't have help texts. By default, we display
0408   ///                         only options that are not hidden and have help
0409   ///                         texts.
0410   void printHelp(raw_ostream &OS, const char *Usage, const char *Title,
0411                  bool ShowHidden = false, bool ShowAllAliases = false,
0412                  Visibility VisibilityMask = Visibility()) const;
0413
0414   void printHelp(raw_ostream &OS, const char *Usage, const char *Title,
0415                  unsigned FlagsToInclude, unsigned FlagsToExclude,
0416                  bool ShowAllAliases) const;
0417
0418 private:
0419   void internalPrintHelp(raw_ostream &OS, const char *Usage, const char *Title,
0420                          bool ShowHidden, bool ShowAllAliases,
0421                          std::function<bool(const Info &)> ExcludeOption,
0422                          Visibility VisibilityMask) const;
0423 };
0424
0425 /// Specialization of OptTable
0426 class GenericOptTable : public OptTable {
0427 protected:
0428   GenericOptTable(const StringTable &StrTable,
0429                   ArrayRef<StringTable::Offset> PrefixesTable,
0430                   ArrayRef<Info> OptionInfos, bool IgnoreCase = false);
0431 };
0432
0433 class PrecomputedOptTable : public OptTable {
0434 protected:
0435   PrecomputedOptTable(const StringTable &StrTable,
0436                       ArrayRef<StringTable::Offset> PrefixesTable,
0437                       ArrayRef<Info> OptionInfos,
0438                       ArrayRef<StringTable::Offset> PrefixesUnionOffsets,
0439                       bool IgnoreCase = false)
0440       : OptTable(StrTable, PrefixesTable, OptionInfos, IgnoreCase) {
0441     for (auto PrefixOffset : PrefixesUnionOffsets)
0442       PrefixesUnion.push_back(StrTable[PrefixOffset]);
0443     buildPrefixChars();
0444   }
0445 };
0446
0447 } // end namespace opt
0448
0449 } // end namespace llvm
0450
0451 #define LLVM_MAKE_OPT_ID_WITH_ID_PREFIX(                                       \
0452     ID_PREFIX, PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, ID, KIND, GROUP, ALIAS,  \
0453     ALIASARGS, FLAGS, VISIBILITY, PARAM, HELPTEXT, HELPTEXTSFORVARIANTS,       \
0454     METAVAR, VALUES)                                                           \
0455   ID_PREFIX##ID
0456
0457 #define LLVM_MAKE_OPT_ID(PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, ID, KIND,      \
0458                          GROUP, ALIAS, ALIASARGS, FLAGS, VISIBILITY, PARAM,    \
0459                          HELPTEXT, HELPTEXTSFORVARIANTS, METAVAR, VALUES)      \
0460   LLVM_MAKE_OPT_ID_WITH_ID_PREFIX(OPT_, PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, \
0461                                   ID, KIND, GROUP, ALIAS, ALIASARGS, FLAGS,    \
0462                                   VISIBILITY, PARAM, HELPTEXT,                 \
0463                                   HELPTEXTSFORVARIANTS, METAVAR, VALUES)
0464
0465 #define LLVM_CONSTRUCT_OPT_INFO_WITH_ID_PREFIX(                                \
0466     ID_PREFIX, PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, ID, KIND, GROUP, ALIAS,  \
0467     ALIASARGS, FLAGS, VISIBILITY, PARAM, HELPTEXT, HELPTEXTSFORVARIANTS,       \
0468     METAVAR, VALUES)                                                           \
0469   llvm::opt::OptTable::Info {                                                  \
0470     PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, HELPTEXT, HELPTEXTSFORVARIANTS,     \
0471         METAVAR, ID_PREFIX##ID, llvm::opt::Option::KIND##Class, PARAM, FLAGS,  \
0472         VISIBILITY, ID_PREFIX##GROUP, ID_PREFIX##ALIAS, ALIASARGS, VALUES      \
0473   }
0474
0475 #define LLVM_CONSTRUCT_OPT_INFO(                                               \
0476     PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, ID, KIND, GROUP, ALIAS, ALIASARGS,  \
0477     FLAGS, VISIBILITY, PARAM, HELPTEXT, HELPTEXTSFORVARIANTS, METAVAR, VALUES) \
0478   LLVM_CONSTRUCT_OPT_INFO_WITH_ID_PREFIX(                                      \
0479       OPT_, PREFIXES_OFFSET, PREFIXED_NAME_OFFSET, ID, KIND, GROUP, ALIAS,     \
0480       ALIASARGS, FLAGS, VISIBILITY, PARAM, HELPTEXT, HELPTEXTSFORVARIANTS,     \
0481       METAVAR, VALUES)
0482
0483 #endif // LLVM_OPTION_OPTTABLE_H