[libOption] - Add flag allowing to print options aliases in help text.

[grimar]

Summary

Goint to use it in LLD.
In short this is PR30422, previously LLD did not show
aliases in help text. With this it is possible.

[ruiu]

Please wait until we decide how we print out the lld options in the help message.

[grimar]

In D35476#812068, @ruiu wrote:

Please wait until we decide how we print out the lld options in the help message.

Ok. Going to rebase this after rL308293 though.

But just in case - the way we will choose for LLD (render all or some of aliases)
should not affect this patch (except if we choose possible way to ignore aliases
rendering at all, which I believe not an option).

Because this patch only implements aliases rendering, and hidden flags handling is
independent and already was implemented before this change.

[grimar]

• Rebased.

[grimar]

• Reimplemented.

ShowAliases flag allows to specify that alias should take HelpText from its
parent option. In that case we can have for example:

def auxiliary: S<"auxiliary">, HelpText<"Set DT_AUXILIARY field to the specified name">;
def alias_auxiliary: Separate<["-"], "f">, Alias<auxiliary>;

and show both options in help:

--auxiliary <value> Set DT_AUXILIARY field to the specified name
-f <value>              Set DT_AUXILIARY field to the specified name

Without that change we would render only first line in --help.

[grimar]

• Change argument name, added lost description.

[ruiu]

The new behavior is probably fine, but I don't think you needed to change the parameter name.

[grimar]

In D35476#819118, @ruiu wrote:

The new behavior is probably fine, but I don't think you needed to change the parameter name.

I changed newly introduced ShowAliases to InferHelpText because first one is not completelly correctly
reflects the action performed.

If we have HelpText specified for alias:
def alias_version_V: Flag<["-"], "V">, Alias<version>, HelpText<"blah blah">;
then regardless of ShowAliases flag value, this option will be shown.
Because old logic prints all options with HelpText at first place (and I did not change it here).

Probably we can name it ShowAllAliases ? With description saying it will trigger rendering all
aliases regardless they have HelpText explicitly set or not.

[grimar]

• Updated in according to my latest comment. (renamed argument to ShowAllAliases).

[ruiu]

LGTM

include/llvm/Option/OptTable.h

194–198

If true, display all options including aliases that don't have help texts. By default, we display only options that are not hidden and have help texts.

lib/Option/OptTable.cpp

478–479

If an alias doesn't have a help text, show a help text for the aliased option instead.

include/llvm/Option/OptTable.h

public:
   /// \brief Render the help text for an option table.
   ///
   /// \param OS - The stream to write the help text to.
   /// \param Name - The name to use in the usage line.
   /// \param Title - The title to use in the usage line.
   /// \param FlagsToInclude - If non-zero, only include options with any
   ///                         of these flags set.
   /// \param FlagsToExclude - Exclude options with any of these flags set.
-  void PrintHelp(raw_ostream &OS, const char *Name,
-                 const char *Title, unsigned FlagsToInclude,
-                 unsigned FlagsToExclude) const;
+  /// \param ShowAliases    - If true, then options aliases are rendered.
+  void PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
+                 unsigned FlagsToInclude, unsigned FlagsToExclude,
+                 bool ShowAliases) const;
 
-  void PrintHelp(raw_ostream &OS, const char *Name,
-                  const char *Title, bool ShowHidden = false) const;
+  void PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
+                 bool ShowHidden = false, bool ShowAliases = false) const;
 };
 
 } // end namespace opt
 
 } // end namespace llvm
 
 #endif // LLVM_OPTION_OPTTABLE_H

lib/Option/OptTable.cpp

 //===- OptTable.cpp - Option Table Implementation -------------------------===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
 
+#include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/STLExtras.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/ADT/StringSet.h"
 #include "llvm/Option/Arg.h"
 #include "llvm/Option/ArgList.h"
 #include "llvm/Option/Option.h"
 #include "llvm/Option/OptSpecifier.h"
 #include "llvm/Option/OptTable.h"
case Option::JoinedAndSeparateClass:
     else
       Name += "<value>";
     break;
   }
 
   return Name;
 }
 
+namespace {
+struct OptionInfo {
+  StringRef HelpText;
+  std::string Name;
+};
+} // namespace
+
 static void PrintHelpOptionList(raw_ostream &OS, StringRef Title,
-                                std::vector<std::pair<std::string,
-                                const char*>> &OptionHelp) {
+                                std::map<unsigned, OptionInfo> &Options) {
   OS << Title << ":\n";
 
   // Find the maximum option length.
   unsigned OptionFieldWidth = 0;
-  for (unsigned i = 0, e = OptionHelp.size(); i != e; ++i) {
-    // Skip titles.
-    if (!OptionHelp[i].second)
-      continue;
-
+  for (auto &P : Options) {
     // Limit the amount of padding we are willing to give up for alignment.
-    unsigned Length = OptionHelp[i].first.size();
+    unsigned Length = P.second.Name.size();
     if (Length <= 23)
       OptionFieldWidth = std::max(OptionFieldWidth, Length);
   }
 
   const unsigned InitialPad = 2;
-  for (unsigned i = 0, e = OptionHelp.size(); i != e; ++i) {
-    const std::string &Option = OptionHelp[i].first;
-    int Pad = OptionFieldWidth - int(Option.size());
-    OS.indent(InitialPad) << Option;
+  for (auto &P : Options) {
+    OptionInfo &Opt = P.second;
+    OS.indent(InitialPad) << Opt.Name;
 
     // Break on long option names.
+    int Pad = OptionFieldWidth - int(Opt.Name.size());
     if (Pad < 0) {
       OS << "\n";
       Pad = OptionFieldWidth + InitialPad;
     }
-    OS.indent(Pad + 1) << OptionHelp[i].second << '\n';
+    OS.indent(Pad + 1) << Opt.HelpText << '\n';
   }
+
+  OS << "\n";
 }
 
 static const char *getOptionHelpGroup(const OptTable &Opts, OptSpecifier Id) {
   unsigned GroupID = Opts.getOptionGroupID(Id);
 
   // If not in a group, return the default help group.
   if (!GroupID)
     return "OPTIONS";
 
   // Abuse the help text of the option groups to store the "help group"
   // name.
   //
   // FIXME: Split out option groups.
   if (const char *GroupHelp = Opts.getOptionHelpText(GroupID))
     return GroupHelp;
 
   // Otherwise keep looking.
   return getOptionHelpGroup(Opts, GroupID);
 }
 
 void OptTable::PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
-                         bool ShowHidden) const {
+                         bool ShowHidden, bool ShowAliases) const {
   PrintHelp(OS, Name, Title, /*Include*/ 0, /*Exclude*/
-            (ShowHidden ? 0 : HelpHidden));
+            (ShowHidden ? 0 : HelpHidden), ShowAliases);
 }
 
-
 void OptTable::PrintHelp(raw_ostream &OS, const char *Name, const char *Title,
-                         unsigned FlagsToInclude,
-                         unsigned FlagsToExclude) const {
+                         unsigned FlagsToInclude, unsigned FlagsToExclude,
+                         bool ShowAliases) const {
   OS << "OVERVIEW: " << Title << "\n";
   OS << '\n';
   OS << "USAGE: " << Name << " [options] <inputs>\n";
   OS << '\n';
 
-  // Render help text into a map of group-name to a list of (option, help)
-  // pairs.
-  using helpmap_ty =
-      std::map<std::string, std::vector<std::pair<std::string, const char*>>>;
-  helpmap_ty GroupedOptionHelp;
-
+  std::map<std::string, std::map<unsigned, OptionInfo>> Groups;
   for (unsigned i = 0, e = getNumOptions(); i != e; ++i) {
     unsigned Id = i + 1;
 
     // FIXME: Split out option groups.
     if (getOptionKind(Id) == Option::GroupClass)
       continue;
 
     unsigned Flags = getInfo(Id).Flags;
     if (FlagsToInclude && !(Flags & FlagsToInclude))
       continue;
     if (Flags & FlagsToExclude)
       continue;
 
-    if (const char *Text = getOptionHelpText(Id)) {
-      const char *HelpGroup = getOptionHelpGroup(*this, Id);
-      const std::string &OptName = getOptionHelpName(*this, Id);
-      GroupedOptionHelp[HelpGroup].push_back(std::make_pair(OptName, Text));
-    }
+    if (const char *Text = getOptionHelpText(Id)) {
+      OptionInfo &Opt = Groups[HelpGroup][Id];
+      Opt.HelpText = Text;
+      Opt.Name = getOptionHelpName(*this, Id) + Opt.Name;
+      continue;
     }
 
-  for (helpmap_ty::iterator it = GroupedOptionHelp .begin(),
-         ie = GroupedOptionHelp.end(); it != ie; ++it) {
-    if (it != GroupedOptionHelp .begin())
-      OS << "\n";
-    PrintHelpOptionList(OS, it->first, it->second);
+    const Option Alias = getOption(Id).getAlias();
+    if (!ShowAliases || !Alias.isValid() || !getOptionHelpText(Alias.getID()))
+      continue;
+
+    OptionInfo &Opt = Groups[HelpGroup][Alias.getID()];
+    Opt.Name += ", " + getOptionHelpName(*this, Id);
   }
 
+  for (auto &G : Groups)
+    PrintHelpOptionList(OS, G.first, G.second);
+
   OS.flush();
 }