/// <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 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>
/// 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>
/// 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 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));
}
