PsdKit-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems xmlns="http://msh" schema="maml">
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Convert-PsdToXml</command:name>
<maml:description>
<maml:para>Converts a psd1 string to PSD-XML.</maml:para>
</maml:description>
<command:verb>Convert</command:verb>
<command:noun>PsdToXml</command:noun>
</command:details>
<maml:description>
<maml:para>For more details about PSD-XML scenarios see
 
    Import-Module PsdKit
    help about_PsdKit</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Convert-PsdToXml</maml:name>
<command:parameter required="true" position="1" >
<maml:name>InputObject</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" pipelineInput="true (ByValue)" position="1" >
<maml:name>InputObject</maml:name>
<maml:description>
<maml:para>Specifies the input psd1-formatted string.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>[System.Xml.XmlDocument]</maml:name>
</dev:type>
<maml:description>
<maml:para>PSD-XML document representing psd1 content.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Convert-XmlToPsd</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Export-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Import-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Set-PsdXml</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Convert-XmlToPsd</command:name>
<maml:description>
<maml:para>Converts PSD-XML to a psd1 string.</maml:para>
</maml:description>
<command:verb>Convert</command:verb>
<command:noun>XmlToPsd</command:noun>
</command:details>
<maml:description>
<maml:para>For more details about PSD-XML scenarios see
 
    Import-Module PsdKit
    help about_PsdKit
 
Note that the result string includes the trailing new line, if any. Thus,
if you use it with Set-Content then consider to use its -NoNewLine.
Otherwise, the file will have more than one empty lines in the end.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Convert-XmlToPsd</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Xml</maml:name>
<command:parameterValue required="true">XmlNode</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Indent</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Xml</maml:name>
<maml:description>
<maml:para>The input PSD-XML to be converted.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Indent</maml:name>
<maml:description>
<maml:para>Specifies the indentation string. By default it is four spaces unless it is
inferred from the original psd1 imported by Import-PsdXml and stored as the
attribute Indent of the root element Data.
 
Special values:
    1 ~ tab
    2 ~ two spaces
    4 ~ four spaces
    0 ~ no indentation
    empty ~ four spaces</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>[string]</maml:name>
</dev:type>
<maml:description>
<maml:para>psd1-formatted string.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Convert-PsdToXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Export-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Import-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Set-PsdXml</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>ConvertTo-Psd</command:name>
<maml:description>
<maml:para>Converts objects to a psd1-formatted strings.</maml:para>
</maml:description>
<command:verb>ConvertTo</command:verb>
<command:noun>Psd</command:noun>
</command:details>
<maml:description>
<maml:para>Supported objects:
    - [System.Collections.IDictionary] -&gt; @{}
    - [System.Collections.IList] -&gt; @()
    - [PSCustomObject] -&gt; @{}
Supported values:
    - [string], [char], [guid], [version], enum -&gt; single quoted string
    - [DateTime] -&gt; [DateTime] x.ToString(&apos;o&apos;)
    - [bool] -&gt; $true and $false
    - number -&gt; x.ToString()
    - $null
 
Note that the result string does not include the trailing new line. Thus,
if you use ConvertTo-Psd with some Set-Content (save) or Add-Content (log)
then you do not have to use -NoNewLine, it is added by these commands. But
on saving in some other ways you may need to add a new line.</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>ConvertTo-Psd</maml:name>
<command:parameter required="false" position="1" >
<maml:name>InputObject</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Indent</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" pipelineInput="true (ByValue)" position="1" >
<maml:name>InputObject</maml:name>
<maml:description>
<maml:para>The input object to be converted or objects from the pipeline.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Indent</maml:name>
<maml:description>
<maml:para>Specifies the indent string. By default it is four spaces.
 
Special values:
    1 ~ tab
    2 ~ two spaces
    4 ~ four spaces
    0 ~ no indentation
    empty ~ four spaces</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:inputTypes>
<command:inputType>
<dev:type>
<maml:name>[object]</maml:name>
</dev:type>
<maml:description>
<maml:para>Objects to be converted to psd1-formatted strings.</maml:para>
</maml:description>
</command:inputType>
</command:inputTypes>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>[string]</maml:name>
</dev:type>
<maml:description>
<maml:para>psd1-formatted strings.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<command:examples>
<command:example>
<maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
<dev:code># Append log records several times
@{time = Get-Date; text = ...} | ConvertTo-Psd | Add-Content log.psd1
 
# Read log records
Import-Psd log.psd1</dev:code>
</command:example>
</command:examples>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Import-Psd</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Export-PsdXml</command:name>
<maml:description>
<maml:para>Exports PSD-XML to a psd1 file.</maml:para>
</maml:description>
<command:verb>Export</command:verb>
<command:noun>PsdXml</command:noun>
</command:details>
<maml:description>
<maml:para>For more details about PSD-XML scenarios see
 
    Import-Module PsdKit
    help about_PsdKit</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Export-PsdXml</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
<command:parameter required="true" position="2" >
<maml:name>Xml</maml:name>
<command:parameterValue required="true">XmlNode</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Indent</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<maml:description>
<maml:para>Specifies the output file path.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="true" position="2" >
<maml:name>Xml</maml:name>
<maml:description>
<maml:para>The input PSD-XML to be exported.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="named" >
<maml:name>Indent</maml:name>
<maml:description>
<maml:para>Specifies the indentation string. By default it is four spaces unless it is
inferred from the original psd1 imported by Import-PsdXml and stored as the
attribute Indent of the root element Data.
 
Special values:
    1 ~ tab
    2 ~ two spaces
    4 ~ four spaces
    0 ~ no indentation
    empty ~ four spaces</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Convert-PsdToXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Convert-XmlToPsd</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Import-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Set-PsdXml</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Get-PsdXml</command:name>
<maml:description>
<maml:para>Gets node PowerShell data.</maml:para>
</maml:description>
<command:verb>Get</command:verb>
<command:noun>PsdXml</command:noun>
</command:details>
<maml:description>
<maml:para>This command parses and returns the specified node value. It does not
invoke any psd1 code, this is safe like importing psd1 in a usual way.
 
Returned values depend on node types:
 
    String
        [string]
    Number
        [int], [long], [double]
    Variable
        $false, $true, $null
    Array
        [System.Collections.Generic.List[object]]
    Table
        [System.Collections.Specialized.OrderedDictionary]
    Cast
        Values converted to primitive types, e.g. [DateType]
    Item
        One of the above values.
    Comment
        [string]
 
Node children must not include comments, commas, and semicolons. In other
words, Get-PsdXml guarantees that comments and separators are not lost on
using Set-PsdXml.
 
Nodes with included comments, commas, and semicolons should be treated as
usual XML with special PSD structure. This is fiddly and error prone but
doable. Yet it is easier to keep some parts of psd1 simple for Get-PsdXml.
 
For more details about PSD-XML scenarios see
 
    Import-Module PsdKit
    help about_PsdKit</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Get-PsdXml</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Xml</maml:name>
<command:parameterValue required="true">XmlNode</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>XPath</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Xml</maml:name>
<maml:description>
<maml:para>Specifies the input PSD-XML node. It is used as the target or the current
node for the optional XPath expression.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="2" >
<maml:name>XPath</maml:name>
<maml:description>
<maml:para>Optionally specifies the XPath from the input node to the existing target
node. If it is omitted or empty then the input node itself is used as the
target.
 
Examples for a module manifest psd1:
 
    Version and release notes nodes can be specified as:
        //Item[@Key=&quot;ModuleVersion&quot;]
        //Item[@Key=&quot;ReleaseNotes&quot;]
 
    Their exact full paths:
        /Data/Table/Item[@Key=&quot;ModuleVersion&quot;]
        /Data/Table/Item[@Key=&quot;PrivateData&quot;]/Table/Item[@Key=&quot;PSData&quot;]/Table/Item[@Key=&quot;ReleaseNotes&quot;]</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Convert-PsdToXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Convert-XmlToPsd</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Export-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Import-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Set-PsdXml</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Import-Psd</command:name>
<maml:description>
<maml:para>Imports objects from a psd1 file.</maml:para>
</maml:description>
<command:verb>Import</command:verb>
<command:noun>Psd</command:noun>
</command:details>
<maml:description>
<maml:para>This command is similar to:
- Import-LocalizedData but slightly easier to use
- Import-PowerShellDataFile but not just a hashtable</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Import-Psd</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<maml:description>
<maml:para>The input file path.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>[object] [hashtable]</maml:name>
</dev:type>
<maml:description>
<maml:para>Imported object(s), often a single hashtable. But psd1 files may contain
several objects and not necessarily hashtables.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>ConvertTo-Psd</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Import-PsdXml</command:name>
<maml:description>
<maml:para>Imports psd1 file as PSD-XML.</maml:para>
</maml:description>
<command:verb>Import</command:verb>
<command:noun>PsdXml</command:noun>
</command:details>
<maml:description>
<maml:para>For more details about PSD-XML scenarios see
 
    Import-Module PsdKit
    help about_PsdKit</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Import-PsdXml</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Path</maml:name>
<maml:description>
<maml:para>Specifies the input psd1 file path.</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<command:returnValues>
<command:returnValue>
<dev:type>
<maml:name>[System.Xml.XmlDocument]</maml:name>
</dev:type>
<maml:description>
<maml:para>PSD-XML document representing psd1 content.</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Convert-PsdToXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Convert-XmlToPsd</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Export-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Set-PsdXml</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
<command:details>
<command:name>Set-PsdXml</command:name>
<maml:description>
<maml:para>Sets node PowerShell data.</maml:para>
</maml:description>
<command:verb>Set</command:verb>
<command:noun>PsdXml</command:noun>
</command:details>
<maml:description>
<maml:para>This command converts data to XML using ConvertTo-Psd and Convert-PsdToXml.
The result XML or context replaces the specified node or its content. Note
that child comments, commas, and semicolons of the node are not preserved.
 
For more details about PSD-XML scenarios see
 
    Import-Module PsdKit
    help about_PsdKit</maml:para>
</maml:description>
<command:syntax>
<command:syntaxItem>
<maml:name>Set-PsdXml</maml:name>
<command:parameter required="true" position="1" >
<maml:name>Xml</maml:name>
<command:parameterValue required="true">XmlNode</command:parameterValue>
</command:parameter>
<command:parameter required="true" position="2" >
<maml:name>Value</maml:name>
<command:parameterValue required="true">Object</command:parameterValue>
</command:parameter>
<command:parameter required="false" position="3" >
<maml:name>XPath</maml:name>
<command:parameterValue required="true">String</command:parameterValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="true" position="1" >
<maml:name>Xml</maml:name>
<maml:description>
<maml:para>Specifies the input PSD-XML node. It is used as the target or the current
node for the optional XPath expression.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="true" position="2" >
<maml:name>Value</maml:name>
<maml:description>
<maml:para>Specifies the new node value.</maml:para>
</maml:description>
</command:parameter>
<command:parameter required="false" position="3" >
<maml:name>XPath</maml:name>
<maml:description>
<maml:para>Optionally specifies the XPath from the input node to the existing target
node. If it is omitted or empty then the input node itself is used as the
target.
 
Examples for a module manifest psd1:
 
    Version and release notes nodes can be specified as:
        //Item[@Key=&quot;ModuleVersion&quot;]
        //Item[@Key=&quot;ReleaseNotes&quot;]
 
    Their exact full paths:
        /Data/Table/Item[@Key=&quot;ModuleVersion&quot;]
        /Data/Table/Item[@Key=&quot;PrivateData&quot;]/Table/Item[@Key=&quot;PSData&quot;]/Table/Item[@Key=&quot;ReleaseNotes&quot;]</maml:para>
</maml:description>
</command:parameter>
</command:parameters>
<maml:relatedLinks>
<maml:navigationLink>
<maml:linkText>Convert-PsdToXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Convert-XmlToPsd</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Export-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Import-PsdXml</maml:linkText>
</maml:navigationLink>
<maml:navigationLink>
<maml:linkText>Get-PsdXml</maml:linkText>
</maml:navigationLink>
</maml:relatedLinks>
</command:command>
</helpItems>