PSModuleDevTool

1.0.0.1

bin/PSHelpXml.ps1

#Requires -Assembly 'System.Xml'

#region public
# . $PSScriptRoot\PublicFunction.ps1
#endregion public

#region Add-HelpItemNode
function Script:Add-Paragraph {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [Alias("i", "Text", "Content")]
        [string[]]
        $InputObject,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    process {
        foreach ($_ in $InputObject) {
            $Root | Add-ChildNode "maml:para" -InnerText $_ -OutNull
        }
    }
}

function Script:Add-Description {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [Alias("i", "Text", "Content")]
        [string[]]
        $InputObject = @(),

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    begin {
        Write-Verbose "Creat xml element - maml:description"
    }

    process {
        $Root |
            Add-ChildNode "maml:description" |
            Script:Add-Paragraph $InputObject
    }
}

function Script:Add-Details {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [string]
        $CommandName,

        [Parameter(Position = 1)]
        [string[]]
        $Description,

        [Parameter(Position = 2)]
        [string[]]
        $Copyright,

        [Parameter(Position = 3)]
        [string[]]
        $Version,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    begin {
        Write-Verbose "Creat xml element - command:details"
    }

    process {
        $NameCache = $CommandName.Trim().Split(" -", [System.StringSplitOptions]1)
        $DetailsNode = $Root | Add-ChildNode "command:details"

        $DetailsNode | Add-ChildNode "command:name" $($NameCache -join "-") -OutNull
        $DetailsNode | Script:Add-Description $Description
        $DetailsNode |
            Add-ChildNode "maml:copyright" |
            Script:Add-Paragraph $Copyright
        $DetailsNode |
            Add-ChildNode "command:version" |
            Script:Add-Paragraph $Version
        $DetailsNode | Add-ChildNode "command:verb" $NameCache[0] -OutNull
        $DetailsNode | Add-ChildNode "command:noun" $NameCache[1] -OutNull
    }
}

function Script:Add-SyntaxItem {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [string]
        $Name,

        [Parameter(Position = 1)]
        [hashtable[]]
        $Parameters,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    begin {
        Write-Verbose "Creat xml element - command:syntax"
    }

    process {
        $SyntaxItemNode = $Root | Add-ChildNode "command:syntaxItem"
        $SyntaxItemNode | Add-ChildNode "maml:name" $Name -OutNull

        foreach ($item in $Parameters) {
            $SyntaxItemNode | Script:Add-Parameter @item
        }
    }
}

function Script:Add-Parameter {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [string]
        $ParamName,

        [Parameter(Position = 1)]
        [Alias("Values")]
        [string[]]
        $ParamValues,

        [Parameter(Position = 2)]
        [Alias("Mandatory")]
        [bool]
        $Required,

        [Parameter(Position = 3)]
        [Alias("Wild", "Wildcard", "WildcardChar")]
        [bool]
        $Globbing,

        [Parameter(Position = 4)]
        [Alias("Pipeline")]
        [bool]
        $PipelineInput,

        [Parameter(Position = 5)]
        [ValidatePattern("^\d+|named$")]
        [string]
        $Position = "named",

        [Parameter(Position = 6)]
        [Alias("Default")]
        [string]
        $DefaultValue = "None",

        [Parameter(Position = 6)]
        [string[]]
        $Description,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    begin {
        Write-Verbose "Creat xml element - command:parameter"
    }

    process {
        $ParamNode = $Root | Add-ChildNode "command:parameter"
        $ParamNode.SetAttribute("required", $Required.ToString().ToLower())
        $ParamNode.SetAttribute("position", $Position.ToLower())
        $ParamNode.SetAttribute("globbing", $Globbing.ToString().ToLower())
        $ParamNode.SetAttribute("pipelineInput", $PipelineInput.ToString().ToLower())
        $ParamNode.SetAttribute("variableLength", "true")

        $ParamNode | Add-ChildNode "maml:name" $ParamName -OutNull
        $ParamNode | Script:Add-Description $Description

        if ($ParamValues.Count -eq 1) {
            $NextNode = $ParamNode
        }
        elseif ($ParamValues.Count -gt 1) {
            $NextNode = $ParamNode | Add-ChildNode "command:parameterValueGroup"
        }

        if ($ParamValues.Count -gt 0) {
            foreach ($value in $ParamValues) {
                $ParamValueNode = $NextNode | Add-ChildNode "command:parameterValue" $value
                $ParamValueNode.SetAttribute("required", "true")
                $ParamValueNode.SetAttribute("variableLength", "false")
            }
        }
    }
}

function Script:Add-InputType {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [Alias("Name")]
        [string]
        $TypeName,

        [Parameter(Position = 1)]
        [Alias("Link")]
        [string]
        $Uri,

        [Parameter(Position = 2)]
        [string[]]
        $Description,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root,

        [Parameter()]
        [switch]$IsReturnValue
    )

    begin {
        $NodeName = if ($IsReturnValue) { "returnValue" } else { "inputType" }
        Write-Verbose "Creat xml element - command:$NodeName"
    }

    process {
        $InputTypeNode = $Root | Add-ChildNode "command:$NodeName"

        $TypeNode = $InputTypeNode | Add-ChildNode "dev:type"
        $TypeNode | Add-ChildNode "maml:name" $TypeName -OutNull
        $TypeNode | Add-ChildNode "maml:uri" $Uri -OutNull

        $InputTypeNode | Script:Add-Description $Description
    }
}

function Script:Add-Example {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [string]
        $Title,

        [Parameter(Position = 1)]
        [Alias("Intro")]
        [string[]]
        $Introduction,

        [Parameter(Position = 2)]
        [string[]]
        $Code,

        [Parameter(Position = 3)]
        [string[]]
        $Remarks,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    begin {
        Write-Verbose "Creat xml element - command:example"
    }

    process {
        $ExampleNode = $Root | Add-ChildNode "command:example"

        $ExampleNode | Add-ChildNode "maml:title" $Title -OutNull
        $ExampleNode |
            Add-ChildNode "maml:introduction" |
            Script:Add-Paragraph $Introduction
        $ExampleNode |
            Add-ChildNode "dev:code" -InnerText ($Code -join " ") -OutNull
        $ExampleNode |
            Add-ChildNode "dev:remarks" |
            Script:Add-Paragraph $Remarks
    }
}

function Script:Add-RelatedLink {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [Alias("Text")]
        [string]
        $LinkText,

        [Parameter(Position = 1)]
        [string]
        $Uri,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root,

        [switch]$PassThru
    )

    begin {
        Write-Verbose "Creat xml element - maml:navigationLink"
    }

    process {
        $LinkNode = $Root | Add-ChildNode "maml:navigationLink"
        $LinkNode | Add-ChildNode "maml:linkText" $LinkText -OutNull
        $LinkNode | Add-ChildNode "maml:uri" $Uri -OutNull

        if ($PassThru) {
            Write-Output $LinkNode
        }
    }
}

function Script:Add-CommandNode {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [hashtable]
        $Details,

        [Parameter(Position = 1)]
        [string[]]
        $Description,

        [Parameter(Position = 2)]
        [hashtable[]]
        $Syntax,

        [Parameter(Position = 3)]
        [hashtable[]]
        $Parameters,

        [Parameter(Position = 4)]
        [hashtable[]]
        $InputTypes,

        [Parameter(Position = 5)]
        [hashtable[]]
        $ReturnValues,

        [Parameter(Position = 6)]
        [hashtable[]]
        $Examples,

        [Parameter(Position = 7)]
        [hashtable[]]
        $RelatedLinks,

        [Parameter(Mandatory, ValueFromPipeline)]
        [System.Xml.XmlElement]
        $Root
    )

    begin {
        Write-Verbose "Creat xml element - command:command"
    }

    process {
        $CommandNode = $Root | Add-ChildNode "command:command"
        $CommandNode.SetAttribute("xmlns:maml", "http://schemas.microsoft.com/maml/2004/10")
        $CommandNode.SetAttribute("xmlns:command", "http://schemas.microsoft.com/maml/dev/command/2004/10")
        $CommandNode.SetAttribute("xmlns:dev", "http://schemas.microsoft.com/maml/dev/2004/10")

        $CommandNode | Script:Add-Details @Details

        if ($null -eq $Description -and $Details.Keys -contains "Description") {
            $Description = $Details.Description
        }
        $CommandNode | Script:Add-Description $Description

        $SyntaxNode = $CommandNode | Add-ChildNode "command:syntax"
        foreach ($syntaxItem in $Syntax) {
            $SyntaxNode | Script:Add-SyntaxItem @syntaxItem
        }

        $ParamsNode = $CommandNode | Add-ChildNode "command:parameters"
        foreach ($param in $Parameters) {
            $ParamsNode | Script:Add-Parameter @param
        }

        $InputTypesNode = $CommandNode | Add-ChildNode "command:inputTypes"
        foreach ($input in $InputTypes) {
            $InputTypesNode | Script:Add-InputType @input
        }

        $ReturnValuesNode = $CommandNode | Add-ChildNode "command:returnValues"
        foreach ($return in $ReturnValues) {
            $ReturnValuesNode | Script:Add-InputType @return -IsReturnValue
        }

        $CommandNode | Add-ChildNode "command:terminatingErrors" -OutNull
        $CommandNode | Add-ChildNode "command:nonTerminatingErrors" -OutNull

        $ExamplesNode = $CommandNode | Add-ChildNode "command:examples"
        foreach ($example in $Examples) {
            $ExamplesNode | Script:Add-Example @example
        }

        $RelatedLinksNode = $CommandNode | Add-ChildNode "command:relatedLinks"
        foreach ($link in $RelatedLinks) {
            $RelatedLinksNode | Script:Add-RelatedLink @link
        }
    }
}

function Add-HelpItemNode {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0)]
        [Alias("Cmds")]
        [hashtable[]]
        $Commands,

        [Parameter(Position = 1)]
        [string]
        $OutXml
    )

    Write-Verbose "Start converting helpItem"
    $Script:doc = [xml]::new()
    $null = $Script:doc.AppendChild($Script:doc.CreateXmlDeclaration("1.0", "utf-8", $null))
    $helpItems = $Script:doc.AppendChild($Script:doc.CreateElement("helpItems"))
    $helpItems.SetAttribute("xmlns", "http://msh")
    $helpItems.SetAttribute("schema", "maml")

    foreach ($_ in $Commands) {
        $helpItems | Script:Add-CommandNode @_
    }

    if (-not [string]::IsNullOrEmpty($OutXml)) {
        $Script:doc.Save($OutXml)
        Write-Verbose "Save in $OutXml"
    }
}
#endregion Add-HelpItemNode

#region ConvertTo-PSHelpXml
function Script:ConvertTo-Syntax {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, ValueFromPipeline)]
        [string]
        $InputObject
    )

    process {
        $InputObject = $InputObject -replace "\s*\n\s*(?=\[*-)", " "
        [string[]]$Syntaxs = $InputObject.Split("`n", [StringSplitOptions]1) |
            ForEach-Object { $_ -replace "\s+(?!\[*-)", "" }
        foreach ($_ in $Syntaxs) {
            $Parameters = $_ -split "\s+(?=\[{0,2}-)"
            $Name = $Parameters[0]
            $Parameters = [string[]]($Parameters | Select-Object -Skip 1)
            $Params =
            for ($i = 0; $i -lt $Parameters.Count; $i++) {
                $Values = $($Parameters[$i] -replace "\[{0,2}-(\w+)\]?([<{]?(\S+)[>}])?\]?", '$1-$3').Split(
                    "-|", [System.StringSplitOptions]1)

                [hashtable]$Param = @{
                    ParamName   = $Values[0]
                    ParamValues = $Values | Select-Object -Skip 1
                }

                $Param.Required = $Parameters[$i] -match "^\[?-\w+\]?$|[>}]$"
                if ($Parameters[$i] -match "\[-\w+\]") {
                    $Param.Position = $i
                }

                Write-Output $Param
            }

            Write-Output @{
                Name       = $Name
                Parameters = $Params
            }
        }
    }
}

function Script:ConvertTo-Parameters {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position = 0)]
        [AllowEmptyString()]
        [string[]]
        $InputObject
    )

    process {
        if ($null -eq $InputObject) {
            return
        }

        $InputObject = $InputObject | Where-Object { $_ }
        $InputObject =
        foreach ($item in $InputObject) {
            $item = $item.TrimStart()
            switch ($item[0]) {
                "-" {
                    $Cache = $item.Split("-<> ", [System.StringSplitOptions]1)
                    "Parameters"
                    " ParamName : $($Cache[0])"
                    " ParamValues : $($Cache[1])"
                }
                "#" { " Description : $item" }
                Default { " $item" }
            }
        }

        $(Resolve-PSIndentSyntax $InputObject $null -Recurse).Parameters
    }
}

function Script:ConvertTo-Examples {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position = 0)]
        [AllowEmptyString()]
        [string[]]
        $InputObject
    )

    process {
        if ($null -eq $InputObject) {
            return
        }

        $InputObject =
        foreach ($item in $InputObject) {
            switch -Regex ($item) {
                "^\S" {
                    "Examples"
                    " Title : $item"
                }
                "^\s+(?<Intro>PS\s[^>]+>)\s*(?<Code>.*)" {
                    " Introduction : $($Matches.Intro)"
                    " Code : $($Matches.Code -replace '^+\s*', '')"
                }
                "^\s+\+\s" {
                    " Code : $($item.TrimStart())"
                }
                Default {
                    " Remarks : $($item.TrimStart())"
                }
            }
        }

        $(Resolve-PSIndentSyntax $InputObject $null -Recurse).Examples
    }
}

function Script:ConvertTo-CommandNode {
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, ValueFromPipeline)]
        [Alias("Contents", "Texts")]
        [AllowEmptyString()]
        [string[]]
        $InputObject
    )

    process {
        $Hash = Resolve-PSIndentSyntax $InputObject -CommentPattern $null

        [Ordered]@{
            Details      = @{
                CommandName = $Hash.Synopsis[0]
                Description = $Hash.Synopsis | Select-Object -Skip 1
            }
            Description  = $Hash.Description
            Syntax       = Script:ConvertTo-Syntax $($Hash.Syntax -join "`n")
            Parameters   = Script:ConvertTo-Parameters $Hash.Parameters
            InputTypes   = @{
                TypeName    = $Hash.Inputs[0]
                Description = $Hash.Inputs | Select-Object -Skip 1
            }
            ReturnValues = @{
                TypeName    = $Hash.Outputs[0]
                Description = $Hash.Outputs | Select-Object -Skip 1
            }
            Examples     = Script:ConvertTo-Examples $Hash.Examples
            RelatedLinks = foreach ($_ in $Hash.RelatedLinks) {
                $link = $_.Split(": ", 2, [System.StringSplitOptions]1)
                @{ LinkText = $link[0]; Uri = $link[1] }
            }
        }
    }
}

function ConvertTo-PSHelpXml {
    [CmdletBinding(DefaultParameterSetName = "LoadFile")]
    param (
        [Parameter(Position = 0, ValueFromPipeline, ParameterSetName = "Load")]
        [string[]]
        $InputObject,

        [Parameter(Position = 0, ValueFromPipeline, ParameterSetName = "LoadFile")]
        [string]
        $Path,

        [Parameter(Position = 1, ValueFromPipeline, ParameterSetName = "LoadFile")]
        [Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding]
        $Encoding = "UTF8",

        [Parameter(ParameterSetName = "Load")]
        [Parameter(ParameterSetName = "LoadFile")]
        [Alias("Out")]
        [string]
        $OutXml = $($Path -replace "\.\w+$", ".xml")
    )

    if ($($PSCmdlet.ParameterSetName -eq "LoadFile") -and $(Test-Path $Path)) {
        $InputObject =
        if ($Path.EndsWith(".ps1")) {
            [string[]](& $Path)
        }
        else {
            $(Get-Content $Path -Raw -Encoding $Encoding) -split "^(?=\.Synopsis)", 0, "Multiline" |
                Where-Object { $_ }
        }
    }

    $Commands =
    foreach ($item in $InputObject) {
        Script:ConvertTo-CommandNode $item.Split("`n")
    }
    Add-HelpItemNode -Commands $Commands -OutXml $OutXml
}
#endregion ConvertTo-PSHelpXml