en-US/Yayaml.Module.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems schema="maml" xmlns="http://msh"> <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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Add-YamlFormat</command:name> <command:verb>Add</command:verb> <command:noun>YamlFormat</command:noun> <maml:description> <maml:para>Adds formatting info for use with `ConvertTo-Yaml` to an object.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `Add-YamlFormat` cmdlet can be used to add YAML formatting information to an object to be serialized. Currently the only formatting information that can be set are scalar and collection styles.</maml:para> <maml:para>Scalar values (simple types like strings, ints, etc) can be set to the following styles:</maml:para> <maml:para>+ `Any` - Uses the schema rules</maml:para> <maml:para>+ `Plain` - The value will not be quoted `foo: bar`</maml:para> <maml:para>+ `SingleQuoted` - The value will be quoted with single quotes `foo: 'bar'`</maml:para> <maml:para>+ `DoubleQuoted` - The value will be quoted with double quotes `foo: "bar"`</maml:para> <maml:para>+ `Literal` - The value will use a literal block `foo: |-\n bar`</maml:para> <maml:para>+ `Folded` - The value will use a folding block `foo: >-\n bar`</maml:para> <maml:para>Depending on the value, the emitter might add a tag to the value to avoid any ambiguity when parsing the YAML string. It is not currently possible to control the chomping and indentation values used in the `Literal` and `Folded` styles due to limitations in the underlying dotnet library.</maml:para> <maml:para>Collections values can be set to the following styles:</maml:para> <maml:para>+ `Any` - Uses the schema rules</maml:para> <maml:para>+ `Block` - Dicts become `foo: bar` and lists become `- 1`</maml:para> <maml:para>+ `Flow` - Dicts become `{foo: bar}` and lists become `[1]`</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Add-YamlFormat</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object to add the YAML formatting information to.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CollectionStyle</maml:name> <maml:description> <maml:para>The style to use for collections (dictionaries and lists). Can be:</maml:para> <maml:para>+ `Any`</maml:para> <maml:para>+ `Block`</maml:para> <maml:para>+ `Flow`</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Any</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Block</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Flow</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CollectionStyle</command:parameterValue> <dev:type> <maml:name>CollectionStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the item with which you are working. By default, this cmdlet doesn't generate any output.</maml:para> <maml:para>Typically this does not need to be set for reference types like dictionaries or arrays but it is recommended to use this for simple types like strings or integers. Strings especially can be problematic as they need to be implicitly wrapped as a `PSObject` which this cmdlet will do and output as needed.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ScalarStyle</maml:name> <maml:description> <maml:para>The style used for scalar values (not dictionaries or lists). Can be:</maml:para> <maml:para>+ `Any`</maml:para> <maml:para>+ `Plain`</maml:para> <maml:para>+ `SingleQuoted`</maml:para> <maml:para>+ `DoubleQuoted`</maml:para> <maml:para>+ `Literal`</maml:para> <maml:para>+ `Folded`</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Any</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Plain</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SingleQuoted</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DoubleQuoted</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Literal</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Folded</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">ScalarStyle</command:parameterValue> <dev:type> <maml:name>ScalarStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CollectionStyle</maml:name> <maml:description> <maml:para>The style to use for collections (dictionaries and lists). Can be:</maml:para> <maml:para>+ `Any`</maml:para> <maml:para>+ `Block`</maml:para> <maml:para>+ `Flow`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CollectionStyle</command:parameterValue> <dev:type> <maml:name>CollectionStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The object to add the YAML formatting information to.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Returns an object representing the item with which you are working. By default, this cmdlet doesn't generate any output.</maml:para> <maml:para>Typically this does not need to be set for reference types like dictionaries or arrays but it is recommended to use this for simple types like strings or integers. Strings especially can be problematic as they need to be implicitly wrapped as a `PSObject` which this cmdlet will do and output as needed.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ScalarStyle</maml:name> <maml:description> <maml:para>The style used for scalar values (not dictionaries or lists). Can be:</maml:para> <maml:para>+ `Any`</maml:para> <maml:para>+ `Plain`</maml:para> <maml:para>+ `SingleQuoted`</maml:para> <maml:para>+ `DoubleQuoted`</maml:para> <maml:para>+ `Literal`</maml:para> <maml:para>+ `Folded`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScalarStyle</command:parameterValue> <dev:type> <maml:name>ScalarStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> </dev:type> <maml:description> <maml:para>Any objects piped into this cmdlet will have the formatting information applied.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para>By default, this cmdlet returns no output. When the `-PassThru` switch is specified, the cmdlet will return the extended input value.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>- Example 1 - Set a string to be emitted with a literal block -</maml:title> <dev:code>PS C:\> $str = 'value' | Add-YamlFormat -ScalarStyle Literal -PassThru PS C:\> ConvertTo-Yaml $str # |- # value</dev:code> <dev:remarks> <maml:para>Sets the string variable to be emitted as a literal block. It is important to pipe string values into this cmdlet and use `-PassThru` to capture the formatting value.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2 - Set a dictionary like value to be emitted as a flow block</maml:title> <dev:code>PS C:\> $obj = [PSCustomObject]@{Foo = 1} PS C:\> $obj | Add-YamlFormat -CollectionStyle Flow PS C:\> $obj | ConvertTo-Yaml # {Foo: 1}</dev:code> <dev:remarks> <maml:para>Sets the dictionary like value to be emitted as a flow collection. Unlike the string type, `-PassThru` isn't needed for this to work although it can still be used if desired.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-Yayaml/blob/main/docs/en-US/Add-YamlFormat.md</maml:uri> </maml:navigationLink> </command: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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertFrom-Yaml</command:name> <command:verb>ConvertFrom</command:verb> <command:noun>Yaml</command:noun> <maml:description> <maml:para>Converts a YAML-formatted string to an object usable in PowerShell.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `ConvertFrom-Yaml` cmdlet converts a YAML formatted string to an object that can be read in PowerShell. The shape of this object is dependent on the YAML string that is being converted. Dictionary values are outputted as an `OrderedDictionary` and list values are outputted as an `Object[]`.</maml:para> <maml:para>By default, the YAML 1.2 core schema will be used when parsing values. Use the `-Schema` parameter to control what schema is used or to provide a custom schema handler.</maml:para> <maml:para>To generate a YAML string from any object, use the ConvertTo-Yaml (./ConvertTo-Yaml.md)cmdlet. See about_YamlParsing (./about_YamlParsing.md)for more information on parsing YAML strings.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertFrom-Yaml</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The YAML strings to convert to objects. If multiple strings are specified on the parameter or through the pipeline input, they are joined together with a newline before being parsed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoEnumerate</maml:name> <maml:description> <maml:para>Specifies that the output from the YAML parse operation is not enumerated. If the YAML string has a root object that is a list/array, each entry will be enumerated as individual objects. By specifying `-NoEnumerate`, the list/array itself is output as an individual object preserving the raw array type.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Schema</maml:name> <maml:description> <maml:para>The custom YAML schema to use when parsing the YAML string. Defaults to `Yaml12`. This can be a custom schema generated by New-YamlSchema (./New-YamlSchema.md)or one of the following strings:</maml:para> <maml:para>+ `Blank` - no schema data is used, scalar values are read as strings</maml:para> <maml:para>+ `Yaml11` - YAML 1.1 rules</maml:para> <maml:para>+ `Yaml12` - YAML 1.2 rules</maml:para> <maml:para>+ `Yaml12JSON` - Subset of YAML 1.2 that are stricter for JSON compatibility</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">YamlSchema</command:parameterValue> <dev:type> <maml:name>YamlSchema</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The YAML strings to convert to objects. If multiple strings are specified on the parameter or through the pipeline input, they are joined together with a newline before being parsed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NoEnumerate</maml:name> <maml:description> <maml:para>Specifies that the output from the YAML parse operation is not enumerated. If the YAML string has a root object that is a list/array, each entry will be enumerated as individual objects. By specifying `-NoEnumerate`, the list/array itself is output as an individual object preserving the raw array type.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Schema</maml:name> <maml:description> <maml:para>The custom YAML schema to use when parsing the YAML string. Defaults to `Yaml12`. This can be a custom schema generated by New-YamlSchema (./New-YamlSchema.md)or one of the following strings:</maml:para> <maml:para>+ `Blank` - no schema data is used, scalar values are read as strings</maml:para> <maml:para>+ `Yaml11` - YAML 1.1 rules</maml:para> <maml:para>+ `Yaml12` - YAML 1.2 rules</maml:para> <maml:para>+ `Yaml12JSON` - Subset of YAML 1.2 that are stricter for JSON compatibility</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">YamlSchema</command:parameterValue> <dev:type> <maml:name>YamlSchema</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The strings that will be used as the YAML source. All the inputs will be combined together with a newline to create the final YAML string that will be parsed.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para>The .NET object that was created from the YAML string.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>See about_YamlParsing (./about_YamlParsing.md)for more information around how a YAML string is turnd into an object.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>---------- Example 1 - Convert YAML string to object ----------</maml:title> <dev:code>PS C:\> $obj = ConvertFrom-Yaml -InputObject @' foo: bar '@ PS C:\> $obj.foo # bar</dev:code> <dev:remarks> <maml:para>Converts the YAML string to a Dictionary object. The YAML keys can be accessed in the dictionary like any other dictionary object in PowerShell.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 2 - Convert YAML from file to an object -------</maml:title> <dev:code>PS C:\> Get-Content ci.yml | ConvertFrom-Yaml</dev:code> <dev:remarks> <maml:para>Reads the contents of the file `ci.yml` and converts it from the YAML string to an object.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 3 - Convert list with single element ---------</maml:title> <dev:code>PS C:\> $yaml = @' - entry '@ PS C:\> $obj1 = ConvertFrom-Yaml $yaml PS C:\> $obj2 = ConvertFrom-Yaml $yaml -NoEnumerate PS C:\> $obj1.GetType() # String PS C:\> $obj2.GetType() # object[]</dev:code> <dev:remarks> <maml:para>Parses a YAML string of a list with and without `-NoEnumerate`. The `$obj1` will contain just `entry` as a string as the output was enumerated internally. The `$obj2` will be the array with a single entry of `entry` as the output was not enumerated internally.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------- Example 4 - Convert YAML using 1.2 JSON Schema --------</maml:title> <dev:code>PS C:\> $obj = ConvertFrom-Yaml 'foo: True' -Schema Yaml12JSON PS C:\> $obj.foo.GetType() # String</dev:code> <dev:remarks> <maml:para>Parses a YAML string with the YAML 1.2 JSON Schema. This schema is a stricter subset of the YAML 1.2 Core schema, for example boolean types are only treated as boolean if they are in lower case.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 5 - Convert YAML with custom tag support -------</maml:title> <dev:code>PS C:\> $yaml = @' key: !!hex_string 74657374 '@ PS C:\> $schema = New-YamlSchema -ParseScalar { param ($Value, $Schema) if ($Value.Tag -eq 'tag:yaml.org,2002:hex_string') { $bytes = [System.Convert]::FromHexString($Value.Value) [System.Text.Encoding]::UTF8.GetString($bytes) } else { $Schema.ParseScalar($Value) } } PS C:\> $obj = ConvertFrom-Yaml -InputObject $yaml -Schema $schema PS C:\> $obj.key # test</dev:code> <dev:remarks> <maml:para>Defines a custom schema with a tag handler for the `tag:yaml.org,2002:hex_string` tag. The custom ScriptBlock can be used to change the output object of the scalar value if the desired tag is seen.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-Yayaml/blob/main/docs/en-US/ConvertFrom-Yaml.md</maml:uri> </maml:navigationLink> </command: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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-Yaml</command:name> <command:verb>ConvertTo</command:verb> <command:noun>Yaml</command:noun> <maml:description> <maml:para>Converts an object to a YAML-formatted string.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `ConvertTo-Yaml` cmdlet converts any .NET object to a string in the YAML format. The output format depends on the input object being serialized. The Add-YamlFormat (./Add-YamlFormat.md)cmdlet can be used to control the format of individual values.</maml:para> <maml:para>By default, the YAML 1.2 core schema will be used when creating the values. Use the `-Schema` parameter to control what schema is used or to provide a custom schema handler.</maml:para> <maml:para>To parse a YAML string into an object, use the ConvertFrom-Yaml (./ConvertFrom-Yaml.md)cmdlet. See about_YamlEmitting (./about_yamlEmitting.md)for more information on creating YAML strings.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-Yaml</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The objects to convert to YAML format. This can be null (`$null`) or an empty string. The input objects can also be passed through the pipeline. It can be dangerous to use any dotnet object as it could contain a lot of properties or cyclic references that slow down the serialization process. Try and use your own custom objects created from a dictionary/list/PSCustomObject with only the properties/values that are needed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsArray</maml:name> <maml:description> <maml:para>Will create a YAML list string from the input objects as an array. Use this to ensure the data provided will be a list string even if only 1 value was supplied.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the YAML representation. The default value is `2`. `ConvertTo-Yaml` emits a warning if the number of levels in an input object exceeds this number.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IndentSequence</maml:name> <maml:description> <maml:para>Output block lists with values indented 2 spaces. The default will be to keep the `-` at the same level as the list declaration.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Schema</maml:name> <maml:description> <maml:para>The custom YAML schema to use when parsing the YAML string. Defaults to `Yaml12`. This can be a custom schema generated by New-YamlSchema (./New-YamlSchema.md)or one of the following strings:</maml:para> <maml:para>+ `Blank` - no schema data is used, scalar values are emitted as string</maml:para> <maml:para>+ `Yaml11` - YAML 1.1 rules</maml:para> <maml:para>+ `Yaml12` - YAML 1.2 rules</maml:para> <maml:para>+ `Yaml12JSON` - Subset of YAML 1.2 but contains stricter plain scalar rules for better JSON compatibility</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">YamlSchema</command:parameterValue> <dev:type> <maml:name>YamlSchema</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AsArray</maml:name> <maml:description> <maml:para>Will create a YAML list string from the input objects as an array. Use this to ensure the data provided will be a list string even if only 1 value was supplied.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Depth</maml:name> <maml:description> <maml:para>Specifies how many levels of contained objects are included in the YAML representation. The default value is `2`. `ConvertTo-Yaml` emits a warning if the number of levels in an input object exceeds this number.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IndentSequence</maml:name> <maml:description> <maml:para>Output block lists with values indented 2 spaces. The default will be to keep the `-` at the same level as the list declaration.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The objects to convert to YAML format. This can be null (`$null`) or an empty string. The input objects can also be passed through the pipeline. It can be dangerous to use any dotnet object as it could contain a lot of properties or cyclic references that slow down the serialization process. Try and use your own custom objects created from a dictionary/list/PSCustomObject with only the properties/values that are needed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSObject</command:parameterValue> <dev:type> <maml:name>PSObject</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Schema</maml:name> <maml:description> <maml:para>The custom YAML schema to use when parsing the YAML string. Defaults to `Yaml12`. This can be a custom schema generated by New-YamlSchema (./New-YamlSchema.md)or one of the following strings:</maml:para> <maml:para>+ `Blank` - no schema data is used, scalar values are emitted as string</maml:para> <maml:para>+ `Yaml11` - YAML 1.1 rules</maml:para> <maml:para>+ `Yaml12` - YAML 1.2 rules</maml:para> <maml:para>+ `Yaml12JSON` - Subset of YAML 1.2 but contains stricter plain scalar rules for better JSON compatibility</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">YamlSchema</command:parameterValue> <dev:type> <maml:name>YamlSchema</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Management.Automation.PSObject</maml:name> </dev:type> <maml:description> <maml:para>The objects to convert to a YAML string.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The YAML string created from the objects provided.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This cmdlet does not support anchors/aliases in the output representation.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------- Example 1 - Create YAML string from a hashtable -------</maml:title> <dev:code>PS C:\> @{foo = 'bar'} | ConvertTo-Yaml # foo: bar</dev:code> <dev:remarks> <maml:para>Creates a YAML string `foo: bar` from the hashtable provided. Note hashtables don't have a defined order, use `[Ordered]@{...}` or `[PSCustomObject]@{...}` if the order is important.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2 - Create YAML string from dotnet object with custom depth</maml:title> <dev:code>PS C:\> $item = Get-Item $PSCommandPath PS C:\> $item | ConvertTo-Yaml -Depth 1 -WarningAction SilentlyContinue</dev:code> <dev:remarks> <maml:para>Creates a YAML string representing the `FileInfo` object of the current script. The depth is also lowered to `1` to avoid serializing multiple properties and the warning about the depth being exceeded has been silenced.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 3 - Serialize string with a literal style ------</maml:title> <dev:code>PS C:\> $str = @' Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras rutrum nisl elit, sed elementum tellus porta facilisis. Suspendisse potenti. In tempus lectus et lacus accumsan commodo vel vitae tortor. '@ | Add-YamlFormat -ScalarStyle Literal -PassThru PS C:\> ConvertTo-Yaml @{Key = $str} # Key: |- # Lorem ipsum dolor sit amet, consectetur adipiscing elit. # Cras rutrum nisl elit, sed elementum tellus porta facilisis. # Suspendisse potenti. In tempus lectus et lacus accumsan commodo vel vitae tortor.</dev:code> <dev:remarks> <maml:para>Sets the value format to a `Literal` block (`|-`) for a string in a hashtable. It is important to use `-PassThru` on `Add-YamlFormat` when dealing with string types. See Add-YamlFormat (./Add-YamlFormat.md)for more information.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 4 - Serialize using the JSON schema ---------</maml:title> <dev:code>PS C:\> ConvertTo-Yaml @{foo = @(1, 2, 3)} -Schema Yaml12JSON # {"foo": [1, 2, 3]}</dev:code> <dev:remarks> <maml:para>Serializes the value using the YAML 1.2 JSON schema. This schema uses very similar rules to JSON with dicts/lists using the flow style and scalar values being quoted unless they match a JSON literal like a number.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------- Example 5 - Serialize list inside a dictionary --------</maml:title> <dev:code>PS C:\> @{foo = 1, 2, 3} | ConvertTo-Yaml # foo: # - 1 # - 2 # - 3</dev:code> <dev:remarks> <maml:para>Serializes a list of values inside a dictionary. By default the list values are not indented.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 6 - Serialize list with indented entries -------</maml:title> <dev:code>PS C:\> @{foo = 1, 2, 3} | ConvertTo-Yaml -IndentSequence # foo: # - 1 # - 2 # - 3</dev:code> <dev:remarks> <maml:para>Serializes a list of values inside a dictionary that are indented.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------- Example 7 - Treat input as a list --------------</maml:title> <dev:code>PS C:\> 1 | ConvertTo-Yaml -AsArray # - 1</dev:code> <dev:remarks> <maml:para>Treats the input as a single array value to serialize. Without the `-AsArray` switch, the `1` would be serialized as an integer rather than a list. This is only needed if there is a single value specified for `-InputObject`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-Yayaml/blob/main/docs/en-US/ConvertTo-Yaml.md</maml:uri> </maml:navigationLink> </command: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" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-YamlSchema</command:name> <command:verb>New</command:verb> <command:noun>YamlSchema</command:noun> <maml:description> <maml:para>Creates a YAML schema definition.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The `New-YamlSchema` can be used to create a custom schema for use with YAML parsing and emitting. A schema has finer control over how individual objects are serialized or how the raw YAML values are parsed as an object. The about_YamlEmitting (./about_YamlEmitting.md) and [about_YamlParsing](./about_YamlParsing.md)have more in depth examples of creating and using custom schemas.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-YamlSchema</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BaseSchema</maml:name> <maml:description> <maml:para>The schema to use as the base rules for the schema. Defaults to `Yaml12`. This can be another custom schema generated by New-YamlSchema (./New-YamlSchema.md)or one of the following strings:</maml:para> <maml:para>+ `Blank` - no schema data is used, scalar values are emitted as string</maml:para> <maml:para>+ `Yaml11` - YAML 1.1 rules</maml:para> <maml:para>+ `Yaml12` - YAML 1.2 rules</maml:para> <maml:para>+ `Yaml12JSON` - Subset of YAML 1.2 but contains stricter plain scalar rules for better JSON compatibility</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">YamlSchema</command:parameterValue> <dev:type> <maml:name>YamlSchema</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitMap</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to create a mapping/dictionary value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[System.Collections.IDictionary]$Values`</maml:para> <maml:para>The dictionary value that needs to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitMap($Values)` function can be called to get the base schema to emit the map value using its rules. The ScriptBlock needs to return a ` [Yayaml.MapValue]` object that represents the final value to be serialized to YAML.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">MapEmitter</command:parameterValue> <dev:type> <maml:name>MapEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitScalar</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to create a scalar value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?]$Value`</maml:para> <maml:para>The scalar value that needs to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitScalar($Value)` function can be called to get the base schema to emit the schema value using its rules. The ScriptBlock needs to return a string value that would be used in the YAML node or a `[Yayaml.ScalarValue]` object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScalarEmitter</command:parameterValue> <dev:type> <maml:name>ScalarEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitSequence</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to create a sequence/list value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?[]]$Values`</maml:para> <maml:para>The list of values that need to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitSequence($Values)` function can be called to get the base schema to emit the sequence value using its rules. The ScriptBlock needs to return a `[Yayaml.SequenceValue]` object that represents the final value to be serialized to YAML.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SequenceEmitter</command:parameterValue> <dev:type> <maml:name>SequenceEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitTransformer</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` goes to emit a value and can be used to transform the input object into another value for emitting. This is useful for apply a custom serialization format for specific types rather than relying on the default behaviour.</maml:para> <maml:para>The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?]$Value`</maml:para> <maml:para>The value that needs to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitSequence($Values)` function can be called to get the base schema to emit the sequence value using its rules. The default schema will emit the value as is without any transformation.</maml:para> <maml:para>It is possible to emit a `[Yayaml.MapValue]`, `[Yayaml.ScalarValue]`, or `[Yayaml.SequenceValue]` object which can specify custom YAML formatting options for the object. Returning one of these values will bypass any futher emit actions as it represents the final value to serialize. Otherwise the `-EmitMap`, `-EmitScalar`, and `-EmiSequence` parameters can be used to process the returned value in a more generic fashion for each node type.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TransformEmitter</command:parameterValue> <dev:type> <maml:name>TransformEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IsScalar</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to check if a value is a scalar value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?]$Value`</maml:para> <maml:para>The value that is used by the ScriptBlock to determine if it's a scalar value.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.IsScalar($Value)` function can be called to get the base schema to perform the scalar type check using its rules. The ScriptBlock needs to return a bool value that determines if it's a scalar value. If `$true`, the codebase will call `EmitScalar` with that value and expect the result to be a scalar value rather than a collection.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IsScalarCheck</command:parameterValue> <dev:type> <maml:name>IsScalarCheck</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParseMap</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertFrom-Yaml` needs to parse a mapping/dictionary value. The ScriptBlock is called with 2 values:</maml:para> <maml:para>+ `[Yayaml.MapValue]$Value`</maml:para> <maml:para>The raw map value that is being parsed.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The ScriptBlock needs to return an object that represents the `MapValue` that was being processed. This object is what will be returned by `ConvertFrom-Yaml` for that YAML entry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">MapParser</command:parameterValue> <dev:type> <maml:name>MapParser</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParseScalar</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertFrom-Yaml` needs to parse a scalar value. The ScriptBlock is called with 2 values:</maml:para> <maml:para>+ `[Yayaml.ScalarValue]$Value`</maml:para> <maml:para>The raw scalar value that is being parsed. This object contains the raw YAML string, the tag, and the scalar style.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The ScriptBlock needs to return an object that represents the `ScalarValue` that was being processed. This object is what will be returned by `ConvertFrom-Yaml` for that YAML entry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScalarParser</command:parameterValue> <dev:type> <maml:name>ScalarParser</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParseSequence</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertFrom-Yaml` needs to parse a sequence/list value. The ScriptBlock is called with 2 values:</maml:para> <maml:para>+ `[Yayaml.SequenceValue]$Value`</maml:para> <maml:para>The raw sequence value that is being parsed.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The ScriptBlock needs to return an object that represents the `SequenceValue` that was being processed. This object is what will be returned by `ConvertFrom-Yaml` for that YAML entry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SequenceParser</command:parameterValue> <dev:type> <maml:name>SequenceParser</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>BaseSchema</maml:name> <maml:description> <maml:para>The schema to use as the base rules for the schema. Defaults to `Yaml12`. This can be another custom schema generated by New-YamlSchema (./New-YamlSchema.md)or one of the following strings:</maml:para> <maml:para>+ `Blank` - no schema data is used, scalar values are emitted as string</maml:para> <maml:para>+ `Yaml11` - YAML 1.1 rules</maml:para> <maml:para>+ `Yaml12` - YAML 1.2 rules</maml:para> <maml:para>+ `Yaml12JSON` - Subset of YAML 1.2 but contains stricter plain scalar rules for better JSON compatibility</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">YamlSchema</command:parameterValue> <dev:type> <maml:name>YamlSchema</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitMap</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to create a mapping/dictionary value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[System.Collections.IDictionary]$Values`</maml:para> <maml:para>The dictionary value that needs to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitMap($Values)` function can be called to get the base schema to emit the map value using its rules. The ScriptBlock needs to return a ` [Yayaml.MapValue]` object that represents the final value to be serialized to YAML.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">MapEmitter</command:parameterValue> <dev:type> <maml:name>MapEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitScalar</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to create a scalar value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?]$Value`</maml:para> <maml:para>The scalar value that needs to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitScalar($Value)` function can be called to get the base schema to emit the schema value using its rules. The ScriptBlock needs to return a string value that would be used in the YAML node or a `[Yayaml.ScalarValue]` object.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScalarEmitter</command:parameterValue> <dev:type> <maml:name>ScalarEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitSequence</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to create a sequence/list value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?[]]$Values`</maml:para> <maml:para>The list of values that need to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitSequence($Values)` function can be called to get the base schema to emit the sequence value using its rules. The ScriptBlock needs to return a `[Yayaml.SequenceValue]` object that represents the final value to be serialized to YAML.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SequenceEmitter</command:parameterValue> <dev:type> <maml:name>SequenceEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>EmitTransformer</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` goes to emit a value and can be used to transform the input object into another value for emitting. This is useful for apply a custom serialization format for specific types rather than relying on the default behaviour.</maml:para> <maml:para>The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?]$Value`</maml:para> <maml:para>The value that needs to be emitted.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.EmitSequence($Values)` function can be called to get the base schema to emit the sequence value using its rules. The default schema will emit the value as is without any transformation.</maml:para> <maml:para>It is possible to emit a `[Yayaml.MapValue]`, `[Yayaml.ScalarValue]`, or `[Yayaml.SequenceValue]` object which can specify custom YAML formatting options for the object. Returning one of these values will bypass any futher emit actions as it represents the final value to serialize. Otherwise the `-EmitMap`, `-EmitScalar`, and `-EmiSequence` parameters can be used to process the returned value in a more generic fashion for each node type.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">TransformEmitter</command:parameterValue> <dev:type> <maml:name>TransformEmitter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IsScalar</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertTo-Yaml` needs to check if a value is a scalar value. The ScriptBlock is called with 2 arguments:</maml:para> <maml:para>+ `[object?]$Value`</maml:para> <maml:para>The value that is used by the ScriptBlock to determine if it's a scalar value.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The `$Schema.IsScalar($Value)` function can be called to get the base schema to perform the scalar type check using its rules. The ScriptBlock needs to return a bool value that determines if it's a scalar value. If `$true`, the codebase will call `EmitScalar` with that value and expect the result to be a scalar value rather than a collection.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IsScalarCheck</command:parameterValue> <dev:type> <maml:name>IsScalarCheck</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParseMap</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertFrom-Yaml` needs to parse a mapping/dictionary value. The ScriptBlock is called with 2 values:</maml:para> <maml:para>+ `[Yayaml.MapValue]$Value`</maml:para> <maml:para>The raw map value that is being parsed.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The ScriptBlock needs to return an object that represents the `MapValue` that was being processed. This object is what will be returned by `ConvertFrom-Yaml` for that YAML entry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">MapParser</command:parameterValue> <dev:type> <maml:name>MapParser</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParseScalar</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertFrom-Yaml` needs to parse a scalar value. The ScriptBlock is called with 2 values:</maml:para> <maml:para>+ `[Yayaml.ScalarValue]$Value`</maml:para> <maml:para>The raw scalar value that is being parsed. This object contains the raw YAML string, the tag, and the scalar style.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The ScriptBlock needs to return an object that represents the `ScalarValue` that was being processed. This object is what will be returned by `ConvertFrom-Yaml` for that YAML entry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ScalarParser</command:parameterValue> <dev:type> <maml:name>ScalarParser</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParseSequence</maml:name> <maml:description> <maml:para>A ScriptBlock that is called when `ConvertFrom-Yaml` needs to parse a sequence/list value. The ScriptBlock is called with 2 values:</maml:para> <maml:para>+ `[Yayaml.SequenceValue]$Value`</maml:para> <maml:para>The raw sequence value that is being parsed.</maml:para> <maml:para>+ `[Yayaml.YamlSchema]$Schema`</maml:para> <maml:para>The base schema that was associated with the custom schema. The ScriptBlock needs to return an object that represents the `SequenceValue` that was being processed. This object is what will be returned by `ConvertFrom-Yaml` for that YAML entry.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SequenceParser</command:parameterValue> <dev:type> <maml:name>SequenceParser</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>This cmdlet does not accept any pipeline input.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>Yayaml.YamlSchema</maml:name> </dev:type> <maml:description> <maml:para>The YAML schema that contains the custom handlers that was provided with it. This schema can be used with the `-Schema` parameter on `ConvertFrom-Yaml` and `ConvertTo-Yaml`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------ Example 1 - Change how DateTime values are emitted ------</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -EmitScalar { param ($Value, $Schema) if ($Value -is [DateTime] -or $Value -is [DateTimeOffset]) { $Value.ToString("yyyy-MM-dd") } else { $Schema.EmitScalar($Value) } } PS C:\> ConvertTo-Yaml @{key = (Get-Date)} -Schema $schema # key: 2023-06-23</dev:code> <dev:remarks> <maml:para>Changes the way that `[DateTime]` and `[DateTimeOffset]` values are serialized to emit just `yyyy-MM-dd`. All other scalar types will use the base schema''s rules.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2 - Emit strings that are longer than 20 chars with the literal style</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -EmitScalar { param ($Value, $Schema) if ($Value -is [string] -and $Value.Length -gt 20) { [Yayaml.ScalarValue]@{ Value = $Value Style = 'Literal' } } else { $Schema.EmitScalar($Value) } } PS C:\> $longString = "test`n" * 10 PS C:\> ConvertTo-Yaml -InputObject @{long = $longString; short = 'short'} -Schema $schema # short: short # long: | # test # test # test # test # test # test # test # test # test # test</dev:code> <dev:remarks> <maml:para>Will emit any string value that is longer than 20 characters in the literal block format.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-- Example 3 - Change the list style with a different Schema --</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -BaseSchema Yaml11 -EmitSequence { param ($Values, $Schema) $toEmit = $Schema.EmitSequence($Values) $toEmit.Style = 'Flow' $toEmit } PS C:\> $value1 = [System.Text.Encoding]::UTF8.GetBytes("value1") PS C:\> $value2 = [System.Text.Encoding]::UTF8.GetBytes("value2") PS C:\> ConvertTo-Yaml -InputObject @{foo = $value1, $value2} -Schema $schema # foo: [!!binary dmFsdWUx, !!binary dmFsdWUy]</dev:code> <dev:remarks> <maml:para>Creates a new schema based on the YAML 1.1 rules and a custom sequence emitter that changes the style to `Flow`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4 - Change the dict style to add a new key to each value</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -EmitMap { param ($Values, $Schema) $Values.Id = Get-Random $Schema.EmitMap($Values) } PS C:\> ConvertTo-Yaml -InputObject @{entry1 = @{foo = 'bar'}; entry2 = @{foo = 'bar'}} -Schema $schema # entry2: # foo: bar # Id: 1663235921 # entry1: # foo: bar # Id: 33594040 # Id: 1517166188</dev:code> <dev:remarks> <maml:para>Creates a new schema that adds a key `Id` to each dict value that will be emitted.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 5 - Emit a specific type as a scalar value ------</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -IsScalar { param ($Value) $Value -is [System.IO.FileSystemInfo] } PS C:\> ConvertTo-Yaml -InputObject @{foo = Get-Item $pwd} -Schema $schema # foo: C:\</dev:code> <dev:remarks> <maml:para>Will treat any `FileSystemInfo` objects as a scalar type. The default behaviour for Scalar values is to stringify the value. A custom `-EmitScalar` ScriptBlock can also be used if custom rules for stringifying the new types is desired.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-- Example 6 - Provide a custom transformer for a custom type --</maml:title> <dev:code>PS C:\> class MyClass { [string]$Title [string]$Description } PS C:\> $schema = New-YamlSchema -EmitTransformer { param($Value, $Schema) if ($Value -is [MyClass]) { [Ordered]@{ Title = $Value.Title Description = $Value.Description | Add-YamlFormat -ScalarStyle Literal -PassThru } } else { $Schema.EmitTransformer($Value) } } PS C:\> $obj = [MyClass]@{Title = 'Module'; Description = 'Information for the module'} PS C:\> $obj | ConvertTo-Yaml -Schema $schema # Title: Module # Description: |- # Information for the module</dev:code> <dev:remarks> <maml:para>Applies a custom transformation for any `MyClass` object that is being converted. This transformation ensures the `$Description` property is emitted in the literal scalar style. Any other object is treated as normal.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 7 - Provide a custom transformer without further processing</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -EmitTransformer { param($Value, $Schema) if ($Value -is [string]) { $style = if ($Value.Length -ge 60) { 'Literal' } else { 'DoubleQuoted' } [Yayaml.ScalarValue]@{ Value = $Value Style = $style } } else { $Schema.EmitTransformer($Value) } } PS C:\> $obj = @( "$('a' * 20)`n$('b' * 20)`n" "$('a' * 20)`n$('b' * 20)`n$('c' * 20)`n$('d' * 20)" ) PS C:\> $obj | ConvertTo-Yaml -Schema $schema -AsArray # - "aaaaaaaaaaaaaaaaaaaa\nbbbbbbbbbbbbbbbbbbbb\n" # - |- # aaaaaaaaaaaaaaaaaaaa # bbbbbbbbbbbbbbbbbbbb # cccccccccccccccccccc # dddddddddddddddddddd</dev:code> <dev:remarks> <maml:para>Applies a custom transformation to transform any string to a specific scalar format. Any string less than 60 characters will be enclosed in double quotes while any greater than 60 will use the literal style. As the transformer outputs the `Yayaml.ScalarValue` there will be no more transformation done on the value during serialization.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 8 - Parse YAML with a custom map handler -------</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -ParseMap { param ($Value, $Schema) # $Value.Values is an OrderedDictionary of the raw mapping value. # $Value.Style is the YAML style - Block or Flow. if ($Value.Values.SpecialKey -eq 'test') { 'override' } else { $Schema.ParseMap($Value) } } PS C:\> $yaml = @' root: entry1: SpecialKey: test ignore: abc entry2: SpecialKey: other keep: abc '@ PS C:\> (ConvertFrom-Yaml $yaml -Schema $schema).root # Name Value # ---- ----- # entry1 override # entry2 {[SpecialKey, other], [keep, abc]}</dev:code> <dev:remarks> <maml:para>Creates a custom map parser that will change the output value if it contains a specific key value. In this case `entry1` will be changed to the value `override` whereas `entry2` is untouched.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---- Example 9 - Parse YAML with a custom sequence handler ----</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -ParseSequence { param ($Values, $Schema) $Values.Values -join "|" } PS C:\> ConvertFrom-Yaml -InputObject 'foo: [1, 2, 3]' -Schema $schema # Name Value # ---- ----- # foo 1|2|3</dev:code> <dev:remarks> <maml:para>Parses all sequence values and changes them to be a string delimited by `|`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----- Example 10 - Parse YAML with a custom scalar handler -----</maml:title> <dev:code>PS C:\> $schema = New-YamlSchema -ParseScalar { param ($Value, $Schema) if ($Value.Tag -eq 'tag:yaml.org,2002:my_tag') { $bytes = [System.Convert]::FromHexString($Value.Value) [System.Text.Encoding]::UTF8.GetString($bytes) } else { $Schema.ParseScalar($Value) } } PS C:\> ConvertFrom-Yaml @' foo: value 1 bar: !!my_tag 76616C75652032 '@ -Schema $schema # Name Value # ---- ----- # foo value 1 # bar value 2</dev:code> <dev:remarks> <maml:para>Adds a handler for scalar values that are tagged with `tag:yaml.org,2002:my_tag`. All other scalar values will continue to use the default schema rules.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-Yayaml/blob/main/docs/en-US/New-YamlSchema.md</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |