MegaBites-AI/Windows-powershell

1// Copyright (c) Microsoft Corporation.2// Licensed under the MIT License.3 4using System.Collections;5using System.Collections.Generic;6 7namespace System.Management.Automation8{9    /// <summary>10    /// Class HelpProviderWithCache provides a pseudo implementation of HelpProvider11    /// at which results are cached in a hashtable so that later retrieval can be12    /// faster.13    /// </summary>14    internal abstract class HelpProviderWithCache : HelpProvider15    {16        /// <summary>17        /// Constructor for HelpProviderWithCache.18        /// </summary>19        internal HelpProviderWithCache(HelpSystem helpSystem) : base(helpSystem)20        {21        }22 23        #region Help Provider Interface24 25        /// <summary>26        /// _helpCache is a hashtable to stores helpInfo.27        /// </summary>28        /// <remarks>29        /// This hashtable is made case-insensitive so that helpInfo can be retrieved case insensitively.30        /// </remarks>31        private readonly Hashtable _helpCache = new Hashtable(StringComparer.OrdinalIgnoreCase);32 33        /// <summary>34        /// Exact match help for a target.35        /// </summary>36        /// <param name="helpRequest">Help request object.</param>37        /// <returns>The HelpInfo found. Null if nothing is found.</returns>38        internal override IEnumerable<HelpInfo> ExactMatchHelp(HelpRequest helpRequest)39        {40            string target = helpRequest.Target;41 42            if (!this.HasCustomMatch)43            {44                if (_helpCache.Contains(target))45                {46                    yield return (HelpInfo)_helpCache[target];47                }48            }49            else50            {51                foreach (string key in _helpCache.Keys)52                {53                    if (CustomMatch(target, key))54                    {55                        yield return (HelpInfo)_helpCache[key];56                    }57                }58            }59 60            if (!this.CacheFullyLoaded)61            {62                DoExactMatchHelp(helpRequest);63                if (_helpCache.Contains(target))64                {65                    yield return (HelpInfo)_helpCache[target];66                }67            }68        }69 70        /// <summary>71        /// This is for child class to indicate that it has implemented72        /// a custom way of match.73        /// </summary>74        /// <value></value>75        protected bool HasCustomMatch { get; set; } = false;76 77        /// <summary>78        /// This is for implementing custom match algorithm.79        /// </summary>80        /// <param name="target">Target to search.</param>81        /// <param name="key">Key used in cache table.</param>82        /// <returns></returns>83        protected virtual bool CustomMatch(string target, string key)84        {85            return target == key;86        }87 88        /// <summary>89        /// Do exact match help for a target.90        /// </summary>91        /// <remarks>92        /// Derived class can choose to either override ExactMatchHelp method to DoExactMatchHelp method.93        /// If ExactMatchHelp is overridden, initial cache checking will be disabled by default.94        /// If DoExactMatchHelp is overridden, cache check will be done first in ExactMatchHelp before the95        /// logic in DoExactMatchHelp is in place.96        /// </remarks>97        /// <param name="helpRequest">Help request object.</param>98        internal virtual void DoExactMatchHelp(HelpRequest helpRequest)99        {100        }101 102        /// <summary>103        /// Search help for a target.104        /// </summary>105        /// <param name="helpRequest">Help request object.</param>106        /// <param name="searchOnlyContent">107        /// If true, searches for pattern in the help content. Individual108        /// provider can decide which content to search in.109        ///110        /// If false, searches for pattern in the command names.111        /// </param>112        /// <returns>A collection of help info objects.</returns>113        internal override IEnumerable<HelpInfo> SearchHelp(HelpRequest helpRequest, bool searchOnlyContent)114        {115            string target = helpRequest.Target;116 117            string wildcardpattern = GetWildCardPattern(target);118 119            HelpRequest searchHelpRequest = helpRequest.Clone();120            searchHelpRequest.Target = wildcardpattern;121            if (!this.CacheFullyLoaded)122            {123                IEnumerable<HelpInfo> result = DoSearchHelp(searchHelpRequest);124                if (result != null)125                {126                    foreach (HelpInfo helpInfoToReturn in result)127                    {128                        yield return helpInfoToReturn;129                    }130                }131            }132            else133            {134                int countOfHelpInfoObjectsFound = 0;135                WildcardPattern helpMatcher = WildcardPattern.Get(wildcardpattern, WildcardOptions.IgnoreCase);136                foreach (string key in _helpCache.Keys)137                {138                    if ((!searchOnlyContent && helpMatcher.IsMatch(key)) ||139                        (searchOnlyContent && ((HelpInfo)_helpCache[key]).MatchPatternInContent(helpMatcher)))140                    {141                        countOfHelpInfoObjectsFound++;142                        yield return (HelpInfo)_helpCache[key];143                        if (helpRequest.MaxResults > 0 && countOfHelpInfoObjectsFound >= helpRequest.MaxResults)144                        {145                            yield break;146                        }147                    }148                }149            }150        }151 152        /// <summary>153        /// Create a wildcard pattern based on a target.154        ///155        /// Here we provide the default implementation of this, covering following156        /// two cases157        ///     a. if target has wildcard pattern, return as it is.158        ///     b. if target doesn't have wildcard pattern, postfix it with *159        ///160        /// Child class of this one may choose to override this function.161        /// </summary>162        /// <param name="target">Target string.</param>163        /// <returns>Wild card pattern created.</returns>164        internal virtual string GetWildCardPattern(string target)165        {166            if (WildcardPattern.ContainsWildcardCharacters(target))167                return target;168 169            return "*" + target + "*";170        }171 172        /// <summary>173        /// Do search help. This is for child class to override.174        /// </summary>175        /// <remarks>176        /// Child class can choose to override SearchHelp of DoSearchHelp depending on177        /// whether it want to reuse the logic in SearchHelp for this class.178        /// </remarks>179        /// <param name="helpRequest">Help request object.</param>180        /// <returns>A collection of help info objects.</returns>181        internal virtual IEnumerable<HelpInfo> DoSearchHelp(HelpRequest helpRequest)182        {183            yield break;184        }185 186        /// <summary>187        /// Add an help entry to cache.188        /// </summary>189        /// <param name="target">The key of the help entry.</param>190        /// <param name="helpInfo">HelpInfo object as the value of the help entry.</param>191        internal void AddCache(string target, HelpInfo helpInfo)192        {193            _helpCache[target] = helpInfo;194        }195 196        /// <summary>197        /// Get help entry from cache.198        /// </summary>199        /// <param name="target">The key for the help entry to retrieve.</param>200        /// <returns>The HelpInfo in cache corresponding the key specified.</returns>201        internal HelpInfo GetCache(string target)202        {203            return (HelpInfo)_helpCache[target];204        }205 206        /// <summary>207        /// Is cached fully loaded?208        ///209        /// If cache is fully loaded, search/exactmatch Help can short cut the logic210        /// in various help providers to get help directly from cache.211        ///212        /// This indicator is usually set by help providers derived from this class.213        /// </summary>214        /// <value></value>215        protected internal bool CacheFullyLoaded { get; set; } = false;216 217        /// <summary>218        /// This will reset the help cache. Normally this corresponds to a219        /// help culture change.220        /// </summary>221        internal override void Reset()222        {223            base.Reset();224 225            _helpCache.Clear();226            CacheFullyLoaded = false;227        }228 229        #endregion230    }231}232