Cmdlets

Choose a cmdlet from the list on the left or search for a specific cmdlet. Choose a cmdlet from the list or search for a specific cmdlet.
About Help  Providers
 

ConvertFrom-String

ConvertFrom-String

microsoft.powershell.commands.utility.dll

Synopsis

Extracts and parses structured objects from string content.

Syntax

ConvertFrom-String [-Delimiter] [-PropertyNames] [-InputObject] [<CommonParameters>]

ConvertFrom-String [-TemplateContent] [-TemplateFile] [-InputObject] [<CommonParameters>]

Detailed Description

You can run the ConvertFrom-String cmdlet to add structure to unstructured string content. ConvertFrom-String generates an object by parsing text from a traditional text stream. For each string in the pipeline, the cmdlet splits the input by either a delimiter or a parse expression, and then assigns property names to each of the resulting split elements. You can provide these property names; if you do not, they are automatically generated for you.

The cmdlet’s default parameter set, FromDelimiter, splits exactly on the regular expression delimiter. It does not perform quote matching or delimiter escaping as the Import-Csv cmdlet does.

The cmdlet’s alternate parameter set, FromParseExpression, generates elements from the groups that are captured by a regular expression.

This cmdlet supports two modes: basic delimited parsing, and automatically-generated, example-driven parsing.

Delimited parsing, by default, splits the input at white space, and assigns property names to the resulting groups. You can customize the delimiter by piping the ConvertFrom-String results into one of the Format-* cmdlets, or by adding the Delimiter parameter.

The cmdlet also supports automatically-generated, example-driven parsing based on the FlashExtract research work by Microsoft Research.

Parameters

-Delimiter <String>

A regular expression that identifies the boundary between elements. Elements that are created by the split become properties in the resulting object. The delimiter is ultimately used in a call to System.Text.RegularExpressions.RegularExpression.Split().

Aliases

DEL

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-InputObject <String>

Specifies strings received from the pipeline, or a variable that contains a string object.

Aliases

None

Required?

true

Position

named

Default value

None

Accept pipeline input?

True (ByValue)

Accept wildcard characters?

false

-PropertyNames <String[]>

One or more property names to which to assign split values in the resulting object. Every line of text that you split or parse generates elements that represent property values. If the element is the result of a capture group, and that capture group is named (for example, (?<name>) or (?'name') ), then the name of that capture group is assigned to the property.

If you provide any elements in the PropertyName array, those names are assigned to properties that have not yet been named.

If you provide more property names than there are fields, Windows PowerShell ignores the extra property names. If you do not specify enough property names to name all fields, Windows PowerShell automatically assigns numerical property names to any properties that are not named: P1, P2, etc.

Aliases

PN

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-TemplateContent <String>

Aliases

TC

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-TemplateFile <String>

Specifies a file that contains a template for the desired parsing of the string. In the template file, properties and their values are enclosed in brackets, as shown in the following example. If a property (such as the Name property in this example) (and its associated otherproperties) can appear multiple times, add an asterisk (*) to indicate that this results in multiple records (rather than extracting multiple properties into a single record.

{Name*:Ana Trujillo}

    {City:Redmond}, {State:WA}

    {Name*:Antonio Moreno}

    {City:Renton}, {State:WA}

Aliases

TF

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

Input Type

System.String

Return Type


Notes

None

Examples

Example 1: Split a two-word string into two properties and values

The following example generates an object with default property names, P1 and P2. The results are "P1=Hello" and "P2=World".

PS C:\>"Hello World" | ConvertFrom-String

Example 2: Split a two-word string into two properties and values

The following example generates an object with "P1=He" and "P2=o World", by specifying the "ll" in "Hello " as the delimiter.

PS C:\>"Hello World" | ConvertFrom-String -Delimiter "ll"

Example 3: Split a string by using a parse expression

The following example generates an object with "P1=llo Wo" and "Captured=ld". There is no property name specified for the first property, so Windows PowerShell applies the default property name, P1; but the name Captured is specified in the expression for the second property.

PS C:\>"Hello World" | ConvertFrom-String -ParseExpression "He(ll.*o)r(?<Captured>ld)"

Example 4: Split a string specifying property names

The following example generates an object that contains two properties, FirstWord and SecondWord. The results are "FirstWord=Hello" and "SecondWord=World.

PS C:\>"Hello World" | ConvertFrom-String -PropertyName FirstWord,SecondWord

Example 5: Split a string specifying property types

The following example generates an object with default property names P1 and P2, but property types String and Int (for Integer) are identified. The results are "P1=123" and "P2=456". The second property is an integer, not a string.

PS C:\>"123 456" | ConvertFrom-String -PropertyType String,Int

Online Version
ConvertFrom-StringData
ConvertFrom-Csv
ConvertTo-Xml