about_PsdKit.help.txt
|
TOPIC
about_PsdKit SHORT DESCRIPTION PowerShell data (psd1) tool kit LONG DESCRIPTION The module provides the following commands: - Data persistence via PowerShell data (psd1) files: - ConvertTo-Psd - Converts objects to psd1 strings. - Import-Psd - Imports objects from a psd1 file. - Updates of psd1 files preserving comments and structure: - Convert-PsdToXml - Converts a psd1 string to PSD-XML. - Convert-XmlToPsd - Converts PSD-XML to a psd1 string. - Export-PsdXml - Exports PSD-XML to a psd1 file. - Import-PsdXml - Imports a psd1 file as PSD-XML. - Get-PsdXml - Gets node PowerShell data. - Set-PsdXml - Sets node PowerShell data. PSD-XML import/export scenarios: - Expressions except values and casts are not supported. - New lines, comments, and separators are preserved. - Spaces and tabs are not necessarily preserved. - The order of values is preserved. - Supported data: - Table @{} with items separated by new lines or semicolons - Array @() with values separated by new lines or commas - String single quoted simple or verbatim strings are preserved, other strings are saved as single quoted simple strings - Number numbers with optional hex notation and suffixes - Variable $null, $true, $false other variables are supported but unusual in psd1 - Cast Expressions like [DateTime] '2018-01-01' PSD-XML get/set scenarios: Get-PsdXml and Set-PsdXml work well if you compose the changeable parts of psd1 properly. Namely: - avoid comments - avoid commas, use @() and separate values by new lines - avoid semicolons, separate hashtable items by new lines In this case, you get and set normal PowerShell data, you do not have to know the details of PSD-XML, except some simple XPath expressions, often the same 'Data/Table/Item[@Key="..."]'. Other parts of psd1 files (not supposed to be changed by scripts) are composed as you like, everything except some space formatting is kept when you change data and save. EXAMPLE Write and read psd1 log file # Append log records several times @{time = Get-Date; text = ...} | ConvertTo-Psd | Add-Content log.psd1 # Read log records Import-Psd log.psd1 EXAMPLE Change the version in a psd1 module manifest # Read psd1 as PSD-XML $xml = Import-PsdXml $FilePath # Set the new version Set-PsdXml $xml 1.0.2 'Data/Table/Item[@Key="ModuleVersion"]' # Save changed PSD-XML Export-PsdXml $FilePath $xml EXAMPLE Convert JSON to psd1 $Host | ConvertTo-Json -Depth 1 | ConvertFrom-Json | ConvertTo-Psd PSD-XML SCHEMA With recommended Get-PsdXml and Set-PsdXml you do not have to know much details about the schema, they operate with native PowerShell data. But for some XPath paths, normally simple, some understanding is needed. <Data> The root node. Attributes: Indent: inferred non-default indent (two spaces or one tab) or some custom indent used as default on exporting Nodes: Table, Array, String, Number, Variable, Cast, Comment, NewLine, Comma, Semicolon <Table> Hashtable nodes for `@{}`. Nodes: Item, Comment, NewLine, Semicolon <Item> Hashtable item for `key = value`. Attributes: Key: hashtable key value Type: "" ~ usual not quoted string key "String" ~ quoted string key "Number" ~ numeric key Nodes: same as <Data> <Array> Array nodes for `@()`. Nodes: same as <Data> <String> Attributes: Type: "1" ~ single quoted here-string Text: string value <Number> Text: number value <Variable> Text: variable name without `$` <Cast> Attributes: Type: type literal, e.g. `[DateTime]` Nodes: String, Number, Variable <Comment> Text: comment text including `#` or `<# #>` <NewLine> <Comma> <Semicolon> Empty nodes representing separators. |