MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4namespace System.Management.Automation5{6    /// <summary>7    /// Help request is a set of data to be passed into monad help engine for requesting help contents.8    ///9    /// Help request track information including10    ///11    ///     1. target12    ///     2. category filter13    ///     3. provider14    ///     4. dynamic parameters15    ///     5. components16    ///     6. functionalities17    ///     7. roles18    ///19    /// Upon getting a help request, help engine will validate the help request and send the request to20    /// necessary help providers for processing.21    /// </summary>22    internal class HelpRequest23    {24        /// <summary>25        /// Constructor for HelpRequest.26        /// </summary>27        /// <param name="target"></param>28        /// <param name="helpCategory"></param>29        internal HelpRequest(string target, HelpCategory helpCategory)30        {31            Target = target;32            HelpCategory = helpCategory;33            CommandOrigin = CommandOrigin.Runspace;34        }35 36        /// <summary>37        /// Create a copy of current help request object.38        /// </summary>39        /// <returns></returns>40        internal HelpRequest Clone()41        {42            HelpRequest helpRequest = new HelpRequest(this.Target, this.HelpCategory);43 44            helpRequest.Provider = this.Provider;45            helpRequest.MaxResults = this.MaxResults;46            helpRequest.Component = this.Component;47            helpRequest.Role = this.Role;48            helpRequest.Functionality = this.Functionality;49            helpRequest.ProviderContext = this.ProviderContext;50            helpRequest.CommandOrigin = CommandOrigin;51 52            return helpRequest;53        }54 55        /// <summary>56        /// Defines which provider the user seeking help is curious about.57        /// </summary>58        internal ProviderContext ProviderContext { get; set; }59 60        /// <summary>61        /// Target for help.62        /// </summary>63        /// <value></value>64        internal string Target { get; set; }65 66        /// <summary>67        /// Help category filter.68        /// </summary>69        /// <value></value>70        internal HelpCategory HelpCategory { get; set; } = HelpCategory.None;71 72        /// <summary>73        /// Provider for this help.74        ///75        /// If provider is set and helpCategory is 'Provider', provider help will be returned. (Also76        /// the value of target will be set to this one).77        ///78        /// If provider is set and helpCategory is 'Command', this will add provider specific help79        /// to provider.80        /// </summary>81        /// <value></value>82        internal string Provider { get; set; }83 84        /// <summary>85        /// Maximum number of result to return for this request.86        /// </summary>87        /// <value></value>88        internal int MaxResults { get; set; } = -1;89 90        /// <summary>91        /// Component filter for command help.92        /// </summary>93        /// <value></value>94        internal string[] Component { get; set; }95 96        /// <summary>97        /// Role filter for command help.98        /// </summary>99        /// <value></value>100        internal string[] Role { get; set; }101 102        /// <summary>103        /// Functionality filter for command help.104        /// </summary>105        /// <value></value>106        internal string[] Functionality { get; set; }107 108        /// <summary>109        /// Keeps track of get-help cmdlet call origin. It can be called110        /// directly by the user or indirectly by a script that a user calls.111        /// </summary>112        internal CommandOrigin CommandOrigin { get; set; }113 114        /// <summary>115        /// Following validation will be done, (in order)116        ///117        /// 1. If everything is empty, do default help.118        /// 2. If target is empty, set it to be provider if currently doing provider help only. Otherwise, set it to be *119        /// 3. If any special parameters like component, role, functionality are specified, do command help only.120        /// 4. If command help is requested, search for alias also.121        /// 5. If help category is none, set it to be all.122        /// 6. Don't do default help.123        /// </summary>124        internal void Validate()125        {126            if (string.IsNullOrEmpty(Target)127                && HelpCategory == HelpCategory.None128                && string.IsNullOrEmpty(Provider)129                && Component == null130                && Role == null131                && Functionality == null132            )133            {134                Target = "default";135                HelpCategory = HelpCategory.DefaultHelp;136                return;137            }138 139            if (string.IsNullOrEmpty(Target))140            {141                if (!string.IsNullOrEmpty(Provider) &&142                    (HelpCategory == HelpCategory.None || HelpCategory == HelpCategory.Provider)143                )144                {145                    Target = Provider;146                }147                else148                {149                    Target = "*";150                }151            }152 153            // if either of component/role/functionality is specified then look in the154            // following help categories155            if ((!(Component == null && Role == null && Functionality == null)) &&156                (HelpCategory == HelpCategory.None))157            {158                HelpCategory = HelpCategory.Alias | HelpCategory.Cmdlet | HelpCategory.Function | HelpCategory.Filter | HelpCategory.ExternalScript | HelpCategory.ScriptCommand;159 160                return;161            }162 163            if ((HelpCategory & HelpCategory.Cmdlet) > 0)164            {165                HelpCategory |= HelpCategory.Alias;166            }167 168            if (HelpCategory == HelpCategory.None)169            {170                HelpCategory = HelpCategory.All;171            }172 173            HelpCategory &= ~HelpCategory.DefaultHelp;174 175            return;176        }177    }178}179