/// <summary> /// Splits the string adding indentation before each line /// </summary> /// <param name="str">string to add indentation to</param> /// <param name="numberOfIndents">number of indentations</param> /// <returns>the string indented</returns> private static string AddIndent(string str, int numberOfIndents) { StringBuilder indent = new StringBuilder(); indent.Append(' ', numberOfIndents * HelpParagraphBuilder.IndentSize); return(HelpParagraphBuilder.AddIndent(str, indent.ToString())); }
/// <summary> /// Adds the help notes segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddNotes(bool setting, string sectionTitle) { if (!setting) { return; } PSObject rootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "alertSet") as PSObject; if (rootObject == null) { return; } string note = GetTextFromArray(rootObject, "alert"); if (note == null) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); this.AddText(HelpParagraphBuilder.AddIndent(note), false); this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help text to the paragraph /// </summary> internal void AddTextToParagraphBuilder() { this.ResetAllText(); string strCategory = (HelpParagraphBuilder.GetProperty(this.psObj, "Category")).Value.ToString(); HelpCategory category = HelpCategory.Default; if (String.Compare(strCategory, "DscResource", StringComparison.OrdinalIgnoreCase) == 0) { category = HelpCategory.DscResource; } else if (String.Compare(strCategory, "Class", StringComparison.OrdinalIgnoreCase) == 0) { category = HelpCategory.Class; } if (HelpParagraphBuilder.GetProperty(this.psObj, "Syntax") == null) { if (category == HelpCategory.Default) { // if there is no syntax, this is not the standard help // it might be an about page this.AddText(this.psObj.ToString(), false); return; } } switch (category) { case HelpCategory.Class: this.AddDescription(HelpWindowSettings.Default.HelpSynopsysDisplayed, HelpWindowResources.SynopsisTitle, "Introduction"); this.AddMembers(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.PropertiesTitle); this.AddMembers(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.MethodsTitle); break; case HelpCategory.DscResource: this.AddStringSection(HelpWindowSettings.Default.HelpSynopsysDisplayed, "Synopsis", HelpWindowResources.SynopsisTitle); this.AddDescription(HelpWindowSettings.Default.HelpDescriptionDisplayed, HelpWindowResources.DescriptionTitle, "Description"); this.AddParameters(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.PropertiesTitle, "Properties", HelpCategory.DscResource); break; default: this.AddStringSection(HelpWindowSettings.Default.HelpSynopsysDisplayed, "Synopsis", HelpWindowResources.SynopsisTitle); this.AddDescription(HelpWindowSettings.Default.HelpDescriptionDisplayed, HelpWindowResources.DescriptionTitle, "Description"); this.AddParameters(HelpWindowSettings.Default.HelpParametersDisplayed, HelpWindowResources.ParametersTitle, "Parameters", HelpCategory.Default); this.AddSyntax(HelpWindowSettings.Default.HelpSyntaxDisplayed, HelpWindowResources.SyntaxTitle); break; } this.AddInputOrOutputEntries(HelpWindowSettings.Default.HelpInputsDisplayed, HelpWindowResources.InputsTitle, "inputTypes", "inputType"); this.AddInputOrOutputEntries(HelpWindowSettings.Default.HelpOutputsDisplayed, HelpWindowResources.OutputsTitle, "returnValues", "returnValue"); this.AddNotes(HelpWindowSettings.Default.HelpNotesDisplayed, HelpWindowResources.NotesTitle); this.AddExamples(HelpWindowSettings.Default.HelpExamplesDisplayed, HelpWindowResources.ExamplesTitle); this.AddNavigationLink(HelpWindowSettings.Default.HelpRelatedLinksDisplayed, HelpWindowResources.RelatedLinksTitle); this.AddStringSection(HelpWindowSettings.Default.HelpRemarksDisplayed, "Remarks", HelpWindowResources.RemarksTitle); }
/// <summary> /// Gets the text from a property of type PSObject[] where the first object has a text property /// </summary> /// <param name="psObj">object to get text from</param> /// <param name="propertyText">property with PSObject[] containing text</param> /// <returns>the text from a property of type PSObject[] where the first object has a text property</returns> private static string GetTextFromArray(PSObject psObj, string propertyText) { PSObject[] introductionObjects = HelpParagraphBuilder.GetPropertyObject(psObj, propertyText) as PSObject[]; if (introductionObjects != null && introductionObjects.Length > 0) { return(GetPropertyString(introductionObjects[0], "text")); } return(null); }
/// <summary> /// Initializes a new instance of the HelpViewModel class /// </summary> /// <param name="psObj">object containing help</param> /// <param name="documentParagraph">paragraph in which help text is built/searched</param> internal HelpViewModel(PSObject psObj, Paragraph documentParagraph) { Debug.Assert(psObj != null, "ensured by caller"); Debug.Assert(documentParagraph != null, "ensured by caller"); this.helpBuilder = new HelpParagraphBuilder(documentParagraph, psObj); this.helpBuilder.BuildParagraph(); this.searcher = new ParagraphSearcher(); this.helpBuilder.PropertyChanged += new PropertyChangedEventHandler(this.HelpBuilder_PropertyChanged); this.helpTitle = String.Format( CultureInfo.CurrentCulture, HelpWindowResources.HelpTitleFormat, HelpParagraphBuilder.GetPropertyString(psObj, "name")); }
/// <summary> /// Initializes a new instance of the HelpViewModel class /// </summary> /// <param name="psObj">object containing help</param> /// <param name="documentParagraph">paragraph in which help text is built/searched</param> internal HelpViewModel(PSObject psObj, Paragraph documentParagraph) { Debug.Assert(psObj != null, "ensured by caller"); Debug.Assert(documentParagraph != null, "ensured by caller"); this.helpBuilder = new HelpParagraphBuilder(documentParagraph, psObj); this.helpBuilder.BuildParagraph(); this.searcher = new ParagraphSearcher(); this.helpBuilder.PropertyChanged += new PropertyChangedEventHandler(this.HelpBuilder_PropertyChanged); this.helpTitle = string.Format( CultureInfo.CurrentCulture, HelpWindowResources.HelpTitleFormat, HelpParagraphBuilder.GetPropertyString(psObj, "name")); }
/// <summary> /// Adds a section that contains only a string /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionName">name of the section to add</param> /// <param name="sectionTitle">title of the section</param> private void AddStringSection(bool setting, string sectionName, string sectionTitle) { string propertyValue; if (!setting || (propertyValue = HelpParagraphBuilder.GetPropertyString(this.psObj, sectionName)) == null) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); this.AddText(HelpParagraphBuilder.AddIndent(propertyValue), false); this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help input or output segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> /// <param name="inputOrOutputProperty">property with the outer object</param> /// <param name="inputOrOutputInnerProperty">property with the inner object</param> private void AddInputOrOutputEntries(bool setting, string sectionTitle, string inputOrOutputProperty, string inputOrOutputInnerProperty) { if (!setting) { return; } PSObject rootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, inputOrOutputProperty) as PSObject; if (rootObject == null) { return; } object[] inputOrOutputObjs; inputOrOutputObjs = HelpParagraphBuilder.GetPropertyObjectArray(rootObject, inputOrOutputInnerProperty); if (inputOrOutputObjs == null || inputOrOutputObjs.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object inputOrOutputObj in inputOrOutputObjs) { PSObject inputOrOutput = inputOrOutputObj as PSObject; if (inputOrOutput == null) { continue; } string type = HelpParagraphBuilder.GetInnerPSObjectPropertyString(inputOrOutput, "type", "name"); string description = GetTextFromArray(inputOrOutput, "description"); this.AddText(HelpParagraphBuilder.AddIndent(type), false); this.AddText("\r\n", false); if (description != null) { this.AddText(HelpParagraphBuilder.AddIndent(description), false); this.AddText("\r\n", false); } } this.AddText("\r\n", false); }
/// <summary> /// Get the object array value of a property. /// </summary> /// <param name="obj">Object containing the property.</param> /// <param name="propertyName">Property with the array value.</param> /// <returns>The object array value of a property.</returns> private static object[] GetPropertyObjectArray(PSObject obj, string propertyName) { object innerObject; if ((innerObject = HelpParagraphBuilder.GetPropertyObject(obj, propertyName)) == null) { return(null); } if (innerObject is PSObject) { return(new[] { innerObject }); } object[] innerObjectArray = innerObject as object[]; return(innerObjectArray); }
/// <summary> /// Adds the help navigation links segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddNavigationLink(bool setting, string sectionTitle) { if (!setting) { return; } PSObject linkRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "RelatedLinks") as PSObject; if (linkRootObject == null) { return; } PSObject[] linkObjects; if ((linkObjects = HelpParagraphBuilder.GetPropertyObject(linkRootObject, "navigationLink") as PSObject[]) == null || linkObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (PSObject linkObject in linkObjects) { string text = GetPropertyString(linkObject, "linkText"); string uri = GetPropertyString(linkObject, "uri"); string linkLine = String.IsNullOrEmpty(uri) ? text : String.Format( CultureInfo.CurrentCulture, HelpWindowResources.LinkTextFormat, text, uri); this.AddText(HelpParagraphBuilder.AddIndent(linkLine), false); this.AddText("\r\n", false); } this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help description segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> /// <param name="propertyName">propertyName that has description</param> private void AddDescription(bool setting, string sectionTitle, string propertyName) { PSObject[] descriptionObjects; if (!setting || (descriptionObjects = HelpParagraphBuilder.GetPropertyObject(this.psObj, propertyName) as PSObject[]) == null || descriptionObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (PSObject description in descriptionObjects) { string descriptionText = GetPropertyString(description, "text"); this.AddText(HelpParagraphBuilder.AddIndent(descriptionText), false); this.AddText("\r\n", false); } this.AddText("\r\n\r\n", false); }
/// <summary> /// Gets the value of a property or null if the value could not be retrieved /// </summary> /// <param name="psObj">object with the property</param> /// <param name="propertyName">property name</param> /// <returns>the value of a property or null if the value could not be retrieved</returns> private static object GetPropertyObject(PSObject psObj, string propertyName) { Debug.Assert(psObj != null, "ensured by caller"); PSPropertyInfo property = HelpParagraphBuilder.GetProperty(psObj, propertyName); if (property == null) { return(null); } object value = null; try { value = property.Value; } catch (ExtendedTypeSystemException) { } return(value); }
/// <summary> /// Adds the help parameters segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> /// <param name="paramPropertyName">name of the property which has properties</param> /// <param name="helpCategory">category of help</param> private void AddParameters(bool setting, string sectionTitle, string paramPropertyName, HelpCategory helpCategory) { if (!setting) { return; } PSObject parameterRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, paramPropertyName) as PSObject; if (parameterRootObject == null) { return; } object[] parameterObjects = null; //Root object for Class has members not parameters. if (helpCategory != HelpCategory.Class) { parameterObjects = HelpParagraphBuilder.GetPropertyObjectArray(parameterRootObject, "parameter"); } if (parameterObjects == null || parameterObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object parameterObj in parameterObjects) { PSObject parameter = parameterObj as PSObject; if (parameter == null) { continue; } string parameterValue = GetPropertyString(parameter, "parameterValue"); string name = GetPropertyString(parameter, "name"); string description = GetTextFromArray(parameter, "description"); string required = GetPropertyString(parameter, "required"); string position = GetPropertyString(parameter, "position"); string pipelineinput = GetPropertyString(parameter, "pipelineInput"); string defaultValue = GetPropertyString(parameter, "defaultValue"); string acceptWildcard = GetPropertyString(parameter, "globbing"); if (String.IsNullOrEmpty(name)) { continue; } // This syntax string is not localized if (helpCategory == HelpCategory.DscResource) { this.AddText(HelpParagraphBuilder.AddIndent(""), false); } else { this.AddText(HelpParagraphBuilder.AddIndent("-"), false); } this.AddText(name, true); string parameterText = String.Format( CultureInfo.CurrentCulture, " <{0}>\r\n", parameterValue); this.AddText(parameterText, false); if (description != null) { this.AddText(HelpParagraphBuilder.AddIndent(description, 2), false); this.AddText("\r\n", false); } this.AddText("\r\n", false); int largestSize = HelpParagraphBuilder.LargestSize( HelpWindowResources.ParameterRequired, HelpWindowResources.ParameterPosition, HelpWindowResources.ParameterDefautValue, HelpWindowResources.ParameterPipelineInput, HelpWindowResources.ParameterAcceptWildcard); // justification of parameter values is not localized string formatString = String.Format( CultureInfo.CurrentCulture, "{{0,-{0}}}{{1}}", largestSize + 2); string tableLine; tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterRequired, required); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); //these are not applicable for Dsc Resource help if (helpCategory != HelpCategory.DscResource) { tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterPosition, position); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterDefautValue, defaultValue); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterPipelineInput, pipelineinput); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); this.AddText("\r\n", false); tableLine = String.Format( CultureInfo.CurrentCulture, formatString, HelpWindowResources.ParameterAcceptWildcard, acceptWildcard); this.AddText(HelpParagraphBuilder.AddIndent(tableLine, 2), false); } this.AddText("\r\n\r\n", false); } this.AddText("\r\n\r\n", false); }
private void FormatMethodData(PSObject member, string name, out string memberText, out string description) { memberText = null; description = null; if (member == null || String.IsNullOrEmpty(name)) { return; } string returnType = null; StringBuilder parameterText = new StringBuilder(); //Get method return type PSObject returnTypeObject = HelpParagraphBuilder.GetPropertyObject(member, "returnValue") as PSObject; if (returnTypeObject != null) { PSObject returnTypeData = HelpParagraphBuilder.GetPropertyObject(returnTypeObject, "type") as PSObject; if (returnTypeData != null) { returnType = GetPropertyString(returnTypeData, "name"); } } //Get method description. PSObject[] methodDescriptions = HelpParagraphBuilder.GetPropertyObject(member, "introduction") as PSObject[]; if (methodDescriptions != null) { foreach (var methodDescription in methodDescriptions) { description = GetPropertyString(methodDescription, "Text"); //If we get an text we do not need to iterate more. if (!String.IsNullOrEmpty(description)) { break; } } } //Get method parameters. PSObject parametersObject = HelpParagraphBuilder.GetPropertyObject(member, "parameters") as PSObject; if (parametersObject != null) { PSObject[] paramObject = HelpParagraphBuilder.GetPropertyObject(parametersObject, "parameter") as PSObject[]; if (paramObject != null) { foreach (var param in paramObject) { string parameterName = GetPropertyString(param, "name"); string parameterType = null; PSObject parameterTypeData = HelpParagraphBuilder.GetPropertyObject(param, "type") as PSObject; if (parameterTypeData != null) { parameterType = GetPropertyString(parameterTypeData, "name"); //If there is no type for the parameter, we expect it is System.Object if (String.IsNullOrEmpty(parameterType)) { parameterType = "object"; } } string paramString = String.Format(CultureInfo.CurrentCulture, "[{0}] ${1},", parameterType, parameterName); parameterText.Append(paramString); } if (String.Compare(parameterText[parameterText.Length - 1].ToString(), ",", StringComparison.OrdinalIgnoreCase) == 0) { parameterText = parameterText.Remove(parameterText.Length - 1, 1); } } } memberText = String.Format(CultureInfo.CurrentCulture, " [{0}] {1}({2})\r\n", returnType, name, parameterText.ToString()); }
private void AddMembers(bool setting, string sectionTitle) { if (!setting || String.IsNullOrEmpty(sectionTitle)) { return; } PSObject memberRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Members") as PSObject; if (memberRootObject == null) { return; } object[] memberObjects = HelpParagraphBuilder.GetPropertyObjectArray(memberRootObject, "member"); if (memberObjects == null) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object memberObj in memberObjects) { string description = null; string memberText = null; PSObject member = memberObj as PSObject; if (member == null) { continue; } string name = GetPropertyString(member, "title"); string type = GetPropertyString(member, "type"); string propertyType = null; if (String.Compare("field", type, StringComparison.OrdinalIgnoreCase) == 0) { PSObject fieldData = HelpParagraphBuilder.GetPropertyObject(member, "fieldData") as PSObject; if (fieldData != null) { PSObject propertyTypeObject = HelpParagraphBuilder.GetPropertyObject(fieldData, "type") as PSObject; if (propertyTypeObject != null) { propertyType = GetPropertyString(propertyTypeObject, "name"); description = GetPropertyString(propertyTypeObject, "description"); } memberText = String.Format(CultureInfo.CurrentCulture, " [{0}] {1}\r\n", propertyType, name); } } else if (String.Compare("method", type, StringComparison.OrdinalIgnoreCase) == 0) { FormatMethodData(member, name, out memberText, out description); } if (!String.IsNullOrEmpty(memberText)) { this.AddText(HelpParagraphBuilder.AddIndent(""), false); this.AddText(memberText, true); if (description != null) { this.AddText(HelpParagraphBuilder.AddIndent(description, 2), false); this.AddText("\r\n", false); } this.AddText("\r\n", false); } } }
/// <summary> /// Adds the help examples segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddExamples(bool setting, string sectionTitle) { if (!setting) { return; } PSObject exampleRootObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Examples") as PSObject; if (exampleRootObject == null) { return; } object[] exampleObjects = HelpParagraphBuilder.GetPropertyObjectArray(exampleRootObject, "example"); if (exampleObjects == null || exampleObjects.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object exampleObj in exampleObjects) { PSObject example = exampleObj as PSObject; if (example == null) { continue; } string introductionText = null; introductionText = GetTextFromArray(example, "introduction"); string codeText = GetPropertyString(example, "code"); string title = GetPropertyString(example, "title"); if (codeText == null) { continue; } if (title != null) { this.AddText(HelpParagraphBuilder.AddIndent(title), false); this.AddText("\r\n", false); } string codeLine = String.Format( CultureInfo.CurrentCulture, "{0}{1}\r\n\r\n", introductionText, codeText); this.AddText(HelpParagraphBuilder.AddIndent(codeLine), false); PSObject[] remarks = HelpParagraphBuilder.GetPropertyObject(example, "remarks") as PSObject[]; if (remarks == null) { continue; } foreach (PSObject remark in remarks) { string remarkText = GetPropertyString(remark, "text"); if (remarkText == null) { continue; } this.AddText(remarkText, false); this.AddText("\r\n", false); } } this.AddText("\r\n\r\n", false); }
/// <summary> /// Adds the help syntax segment /// </summary> /// <param name="setting">true if it should add the segment</param> /// <param name="sectionTitle">title of the section</param> private void AddSyntax(bool setting, string sectionTitle) { PSObject syntaxObject; if (!setting || (syntaxObject = HelpParagraphBuilder.GetPropertyObject(this.psObj, "Syntax") as PSObject) == null) { return; } object[] syntaxItemsObj = HelpParagraphBuilder.GetPropertyObjectArray(syntaxObject, "syntaxItem"); if (syntaxItemsObj == null || syntaxItemsObj.Length == 0) { return; } this.AddText(sectionTitle, true); this.AddText("\r\n", false); foreach (object syntaxItemObj in syntaxItemsObj) { PSObject syntaxItem = syntaxItemObj as PSObject; if (syntaxItem == null) { continue; } string commandName = GetPropertyString(syntaxItem, "name"); object[] parameterObjs = HelpParagraphBuilder.GetPropertyObjectArray(syntaxItem, "parameter"); if (commandName == null || parameterObjs == null || parameterObjs.Length == 0) { continue; } string commandStart = String.Format(CultureInfo.CurrentCulture, "{0} ", commandName); this.AddText(HelpParagraphBuilder.AddIndent(commandStart), false); foreach (object parameterObj in parameterObjs) { PSObject parameter = parameterObj as PSObject; if (parameter == null) { continue; } string parameterValue = GetPropertyString(parameter, "parameterValue"); string position = GetPropertyString(parameter, "position"); string required = GetPropertyString(parameter, "required"); string parameterName = GetPropertyString(parameter, "name"); if (position == null || required == null || parameterName == null) { continue; } string parameterType = parameterValue == null ? String.Empty : String.Format(CultureInfo.CurrentCulture, "<{0}>", parameterValue); string parameterOptionalOpenBrace, parameterOptionalCloseBrace; if (String.Equals(required, "true", StringComparison.OrdinalIgnoreCase)) { parameterOptionalOpenBrace = parameterOptionalCloseBrace = String.Empty; } else { parameterOptionalOpenBrace = "["; parameterOptionalCloseBrace = "]"; } string parameterNameOptionalOpenBrace, parameterNameOptionalCloseBrace; if (String.Equals(position, "named", StringComparison.OrdinalIgnoreCase)) { parameterNameOptionalOpenBrace = parameterNameOptionalCloseBrace = String.Empty; } else { parameterNameOptionalOpenBrace = "["; parameterNameOptionalCloseBrace = "]"; } string parameterPrefix = String.Format( CultureInfo.CurrentCulture, "{0}{1}-", parameterOptionalOpenBrace, parameterNameOptionalOpenBrace); this.AddText(parameterPrefix, false); this.AddText(parameterName, true); string parameterSuffix = String.Format( CultureInfo.CurrentCulture, "{0} {1}{2} ", parameterNameOptionalCloseBrace, parameterType, parameterOptionalCloseBrace); this.AddText(parameterSuffix, false); } string commonParametersText = String.Format( CultureInfo.CurrentCulture, "[<{0}>]\r\n\r\n", HelpWindowResources.CommonParameters); this.AddText(commonParametersText, false); } this.AddText("\r\n", false); }
/// <summary> /// Splits the string adding indentation before each line /// </summary> /// <param name="str">string to add indentation to</param> /// <returns>the string indented</returns> private static string AddIndent(string str) { return(HelpParagraphBuilder.AddIndent(str, 1)); }