MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections.ObjectModel;5 6namespace System.Management.Automation7{8    /// <summary>9    /// Class HelpInfo keeps track of help information to be returned by help system.10    ///11    /// HelpInfo includes information in following aspect,12    ///13    ///     a. Name: the target name for help14    ///     b. Category: what category the help belongs to15    /// This class will be derived to track help info for different help categories like,16    ///     AliasHelpInfo17    ///     CommandHelpInfo18    ///     ProviderHelpInfo19    ///20    /// etc.21    ///22    /// In general, there will be a specific helpInfo child class for each kind of help provider.23    /// </summary>24    internal abstract class HelpInfo25    {26        /// <summary>27        /// Constructor for HelpInfo.28        /// </summary>29        internal HelpInfo()30        {31        }32 33        /// <summary>34        /// Name for help info.35        /// </summary>36        /// <value>Name for help info</value>37        internal abstract string Name38        {39            get;40        }41 42        /// <summary>43        /// Synopsis for help info.44        /// </summary>45        /// <value>Synopsis for help info</value>46        internal abstract string Synopsis47        {48            get;49        }50 51        /// <summary>52        /// Component for help info.53        /// </summary>54        /// <value>Component for help info</value>55        internal virtual string Component56        {57            get { return string.Empty; }58        }59 60        /// <summary>61        /// Role for help info.62        /// </summary>63        /// <value>Role for help ino</value>64        internal virtual string Role65        {66            get { return string.Empty; }67        }68 69        /// <summary>70        /// Functionality for help info.71        /// </summary>72        /// <value>Functionality for help info</value>73        internal virtual string Functionality74        {75            get { return string.Empty; }76        }77 78        /// <summary>79        /// Help category for help info.80        /// </summary>81        /// <value>Help category for help info</value>82        internal abstract HelpCategory HelpCategory83        {84            get;85        }86 87        /// <summary>88        /// Forward help category for this help info.89        /// </summary>90        /// <remarks>91        /// If this is not HelpCategory.None, then some other help provider92        /// (as specified in the HelpCategory bit pattern) need93        /// to process this helpInfo before it can be returned to end user.94        /// </remarks>95        /// <value>Help category to forward this helpInfo to</value>96        internal HelpCategory ForwardHelpCategory { get; set; } = HelpCategory.None;97 98        /// <summary>99        /// Target object in forward-help-provider that should process this HelpInfo.100        /// This will serve as auxiliary information to be passed to forward help provider.101        ///102        /// In the case of AliasHelpInfo, for example, it needs to be forwarded to103        /// CommandHelpProvider to fill in detailed helpInfo. In that case, ForwardHelpCategory104        /// will be HelpCategory.Command and the help target is the cmdlet name that matches this105        /// alias.106        /// </summary>107        /// <value>forward target object name</value>108        internal string ForwardTarget { get; set; } = string.Empty;109 110        /// <summary>111        /// Full help object for this help item.112        /// </summary>113        /// <value>Full help object for this help item</value>114        internal abstract PSObject FullHelp115        {116            get;117        }118 119        /// <summary>120        /// Short help object for this help item.121        /// </summary>122        /// <value>Short help object for this help item</value>123        internal PSObject ShortHelp124        {125            get126            {127                if (this.FullHelp == null)128                    return null;129 130                PSObject shortHelpObject = new PSObject(this.FullHelp);131 132                shortHelpObject.TypeNames.Clear();133                shortHelpObject.TypeNames.Add("HelpInfoShort");134 135                return shortHelpObject;136            }137        }138 139        /// <summary>140        /// Returns help information for a parameter(s) identified by pattern.141        /// </summary>142        /// <param name="pattern">Pattern to search for parameters.</param>143        /// <returns>A collection of parameters that match pattern.</returns>144        /// <remarks>145        /// The base method returns an empty list.146        /// </remarks>147        internal virtual PSObject[] GetParameter(string pattern)148        {149            return Array.Empty<PSObject>();150        }151 152        /// <summary>153        /// Returns the Uri used by get-help cmdlet to show help154        /// online.155        /// </summary>156        /// <returns>157        /// Null if no Uri is specified by the helpinfo or a158        /// valid Uri.159        /// </returns>160        /// <exception cref="InvalidOperationException">161        /// Specified Uri is not valid.162        /// </exception>163        internal virtual Uri GetUriForOnlineHelp()164        {165            return null;166        }167 168        /// <summary>169        /// Returns true if help content in help info matches the170        /// pattern contained in <paramref name="pattern"/>.171        /// The underlying code will usually run pattern.IsMatch() on172        /// content it wants to search.173        /// </summary>174        /// <param name="pattern"></param>175        /// <returns></returns>176        internal virtual bool MatchPatternInContent(WildcardPattern pattern)177        {178            // this is base class implementation..derived classes can choose179            // what is best to them.180            return false;181        }182 183        /// <summary>184        /// Add common help properties to the helpObject which is in PSObject format.185        ///186        /// Intrinsic help properties include properties like,187        ///     Name,188        ///     Synopsis189        ///     HelpCategory190        /// etc.191        ///192        /// Since help object from different help category has different format, it is193        /// needed that we generate these basic information uniformly in the help object194        /// itself.195        ///196        /// This function is normally called at the end of each child class constructor.197        /// </summary>198        /// <returns></returns>199        protected void AddCommonHelpProperties()200        {201            if (this.FullHelp == null)202                return;203 204            if (this.FullHelp.Properties["Name"] == null)205            {206                this.FullHelp.Properties.Add(new PSNoteProperty("Name", this.Name));207            }208 209            if (this.FullHelp.Properties["Category"] == null)210            {211                this.FullHelp.Properties.Add(new PSNoteProperty("Category", this.HelpCategory.ToString()));212            }213 214            if (this.FullHelp.Properties["Synopsis"] == null)215            {216                this.FullHelp.Properties.Add(new PSNoteProperty("Synopsis", this.Synopsis));217            }218 219            if (this.FullHelp.Properties["Component"] == null)220            {221                this.FullHelp.Properties.Add(new PSNoteProperty("Component", this.Component));222            }223 224            if (this.FullHelp.Properties["Role"] == null)225            {226                this.FullHelp.Properties.Add(new PSNoteProperty("Role", this.Role));227            }228 229            if (this.FullHelp.Properties["Functionality"] == null)230            {231                this.FullHelp.Properties.Add(new PSNoteProperty("Functionality", this.Functionality));232            }233        }234 235        /// <summary>236        /// Update common help user-defined properties of the help object which is in PSObject format.237        /// Call this function to update Mshobject after it is created.238        /// </summary>239        /// <remarks>240        /// This function wont create new properties.This will update only user-defined properties created in241        /// <paramref name="AddCommonHelpProperties"/>242        /// </remarks>243        protected void UpdateUserDefinedDataProperties()244        {245            if (this.FullHelp == null)246                return;247 248            this.FullHelp.Properties.Remove("Component");249            this.FullHelp.Properties.Add(new PSNoteProperty("Component", this.Component));250 251            this.FullHelp.Properties.Remove("Role");252            this.FullHelp.Properties.Add(new PSNoteProperty("Role", this.Role));253 254            this.FullHelp.Properties.Remove("Functionality");255            this.FullHelp.Properties.Add(new PSNoteProperty("Functionality", this.Functionality));256        }257 258        #region Error handling259 260        /// <summary>261        /// This is for tracking the set of errors happened during the parsing of262        /// of this helpinfo.263        /// </summary>264        /// <value></value>265        internal Collection<ErrorRecord> Errors { get; set; }266 267        #endregion268    }269}270