Markdown CommandOptions (#2860)

* WIP CommandOptions

* Fix some output issues.

* Simplify word wrapping.

* Add file extensions.

* Change how lookup takes place.
Add appendSplit functions to StringUtil.
Make Categories hold the index range of their options.

* Small improvement.

* Lookup with partial option names.

* Associate user values.

* Encoding flags in the name.

* Refactor setting up of command options.

* Use CommandOptions in slang-options.

* Remove old help text.

* Cache the CommandOptions on the Session.

* Range checking.
Fix bug in the Options handling.

* Extra checks for validity.

* Get categories directly.

* Slight improvements over output.

* Added NameValue types.

* Fix typo.
Remove some now unused diagnostics.
Fix diagnostic in testing, as output has changed.

* Add minimal usage message.

* Remove platform executable extension from diagnostics output.

* Some improvements around getting names from NameValue types.

* Improve some option descriptions.

* Small fixes.

* WIP improvements around CommandOptions.

* Split out CommandOptionsWriter.

* Add links to options.

* Add command line options reference.

* Link to the reference command line information.

* Add quick links.

* Improvements around lookup.
Add categories to linking.

* Small additional fixes.

* Add LinkFlags control.

* Small text fixes.

* Fix typo.

* Fix typo.

* Fix typo.

* Add support for -g and -O using CommandOptions.

* Improve generated doc output/descriptions.
Remove options listed directly in documentation.

1 files changed, 34 insertions, 48 deletions

diff --git a/source/core/slang-command-options.h b/source/core/slang-command-options.h
index a92d4d8f8..8b6d7b0ce 100644
--- a/source/core/slang-command-options.h
+++ b/source/core/slang-command-options.h
@@ -28,6 +28,20 @@ struct CommandOptions
         Base     =  0,              ///< Lookup via category index
     };
 
+       /// A key type that uses the combination of the lookup kind and a name index.
+       /// Maps to a target index that could be a category or an option index.
+    struct NameKey
+    {
+        typedef NameKey ThisType;
+
+        SLANG_FORCE_INLINE bool operator==(const ThisType& rhs) const { return kind == rhs.kind && nameIndex == rhs.nameIndex; }
+        SLANG_FORCE_INLINE bool operator!=(const ThisType& rhs) const { return !(*this == rhs); }
+        HashCode getHashCode() const { return combineHash(Slang::getHashCode(kind), Slang::getHashCode(nameIndex)); }
+
+        LookupKind kind;            ///< The kind of lookup
+        Index nameIndex;            ///< The name index in the pool
+    };
+
     enum class CategoryKind
     {
         Option,             ///< Command line option (like "-D")
@@ -74,6 +88,16 @@ struct CommandOptions
         Flags flags = 0;                        ///< Flags about this option
     };
 
+        /// Get the first name
+    UnownedStringSlice getFirstNameForOption(Index optionIndex);
+        /// Get the first name for the category
+    UnownedStringSlice getFirstNameForCategory(Index categoryIndex);
+
+        /// Get a name key for an opton
+    NameKey getNameKeyForOption(Index optionIndex);
+        /// Get a name key for a category
+    NameKey getNameKeyForCategory(Index optionIndex);
+
         /// Add a category
     Index addCategory(CategoryKind kind, const char* name, const char* description, UserValue userValue = kInvalidUserValue);
         /// Use an already known category. It's an error if the category isn't found
@@ -100,14 +124,14 @@ struct CommandOptions
     void addValuesWithAliases(const ConstArrayView<NameValue>& values);
 
         /// Get the target index based off the name and the kind
-    Index findTargetIndexByName(LookupKind kind, const UnownedStringSlice& name) const;
+    Index findTargetIndexByName(LookupKind kind, const UnownedStringSlice& name, NameKey* outNameKey = nullptr) const;
         /// Given a kind and a user value lookup the target index
     Index findTargetIndexByUserValue(LookupKind kind, UserValue userValue) const;
 
         /// Finds the category by name or -1 if not found
     Index findCategoryByName(const UnownedStringSlice& name) const { return findTargetIndexByName(LookupKind::Category, name); }
         /// Finds the option index by name or -1 if not found
-    Index findOptionByName(const UnownedStringSlice& name) const;
+    Index findOptionByName(const UnownedStringSlice& name) const { return findTargetIndexByName(LookupKind::Option, name); }
         /// Find the option index of a value, using it's category index and the name
     Index findValueByName(Index categoryIndex, const UnownedStringSlice& name) const { return findTargetIndexByName(LookupKind(categoryIndex), name); }
 
@@ -139,9 +163,14 @@ struct CommandOptions
 
         /// Find all of the categories in the usage slice
     void findCategoryIndicesFromUsage(const UnownedStringSlice& usageSlice, List<Index>& outCategories) const;
+
+        /// Splits usage into category slices
+    void splitUsage(const UnownedStringSlice& usageSlice, List<UnownedStringSlice>& outSlices) const;
+
         /// Get all the option names associated with a category index
     void getCategoryOptionNames(Index categoryIndex, List<UnownedStringSlice>& outNames) const;
-    
+    void appendCategoryOptionNames(Index categoryIndex, List<UnownedStringSlice>& outNames) const;
+
         /// Set up a lookup kind from a category index
     static LookupKind makeLookupKind(Index categoryIndex) { return LookupKind(categoryIndex); }
 
@@ -160,6 +189,7 @@ struct CommandOptions
     {
     }
 
+    protected:
         /// Returns name in the m_optionPool or -1 on error
     SlangResult _addOptionName(const UnownedStringSlice& name, Flags flags, Index targetIndex);
     SlangResult _addValueName(const UnownedStringSlice& name, Index categoryIndex, Index targetIndex);
@@ -175,19 +205,7 @@ struct CommandOptions
     UnownedStringSlice _addString(const char* text);
     UnownedStringSlice _addString(const UnownedStringSlice& slice);
 
-    /// A key type that uses the combination of the lookup kind and a name index.
-    /// Maps to a target index that could be a category or an option index.
-    struct NameKey
-    {
-        typedef NameKey ThisType;
-
-        SLANG_FORCE_INLINE bool operator==(const ThisType& rhs) const { return kind == rhs.kind && nameIndex == rhs.nameIndex; }
-        SLANG_FORCE_INLINE bool operator!=(const ThisType& rhs) const { return !(*this == rhs); }
-        HashCode getHashCode() const { return combineHash(Slang::getHashCode(kind), Slang::getHashCode(nameIndex)); }
-
-        LookupKind kind;            ///< The kind of lookup
-        Index nameIndex;            ///< The name index in the pool
-    };
+    Index _findTargetIndexByName(LookupKind kind, const UnownedStringSlice& name, NameKey* outNameKey) const;
 
     struct UserValueKey
     {
@@ -216,38 +234,6 @@ struct CommandOptions
     MemoryArena m_arena;                            ///< For other misc storage
 };
 
-struct CommandOptionsWriter
-{
-    typedef CommandOptions::CategoryKind CategoryKind;
-    
-        /// Append descirption for a category
-    void appendDescriptionForCategory(const CommandOptions& options, Index categoryIndex);
-        /// Appends a description of all of the options
-    void appendDescription(const CommandOptions& options);
-
-        /// Get the builder that string is being written to
-    StringBuilder& getBuilder() { return m_builder; }
-
-        /// Ctor 
-    CommandOptionsWriter():
-        m_indentSlice(toSlice("  "))
-    {
-    }
-
-    Count _getCurrentLineLength();
-
-    void _appendWithWrap(Count indentCount, List<UnownedStringSlice>& slices, const UnownedStringSlice& delimit);
-    void _appendWithWrap(Count indentCount, List<UnownedStringSlice>& lines);
-    void _requireIndent(Count indentCount);
-    void _appendText(Count indentCount, const UnownedStringSlice& text);
-
-
-    UnownedStringSlice m_indentSlice;
-    Count m_lineLength = 80;
-
-    StringBuilder m_builder;
-};
-
 } // namespace Slang
 
 #endif