ConvertFrom-String

Syntax

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

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

Description

The ConvertFrom-String cmdlet extracts and parses structured properties from string content. This cmdlet 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, ByDelimiter, 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, TemplateParsing, generates elements from the groups that are captured by a regular expression. For more information on regular expressions, see about_Regular_Expressions.

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 you can use the Delimiter parameter.

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

Examples

Example 1: Generate an object with default property names

"Hello World" | ConvertFrom-String

P1    P2
--    --
Hello World

This command generates an object with default property names, P1 and P2.

Example 1A: Get to know the generated object

This command generates one object with properties P1, P2; both properties are of String type, by default.

"Hello World" | ConvertFrom-String | Get-Member

TypeName: System.Management.Automation.PSCustomObject

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
P1          NoteProperty string P1=Hello
P2          NoteProperty string P2=World

Example 2: Generate an object with default property names using a delimiter

This command generates an object with a domain and username using the backslash (\) as the delimiter. The backslash character must be escaped with another backslash when using regular expressions.

"Contoso\Administrator" | ConvertFrom-String -Delimiter "\\"

P1      P2
--      --
Contoso Administrator

Example 3: Generate an object that contains two named properties

The following example creates objects from Windows hosts file entries.

$content = Get-Content C:\Windows\System32\drivers\etc\hosts
$content = $content -match "^[^#]"
$content | ConvertFrom-String -PropertyNames IP, Server

IP             Server
--             ------
192.168.7.10   W2012R2
192.168.7.20   W2016
192.168.7.101  WIN8
192.168.7.102  WIN10

The Get-Content cmdlet stores the content of a Windows hosts file in $content. The second command removes any comments at the beginning of the hosts file using a regular expression that matches any line that does not start with (#). The last command converts the remaining text into objects with Server and IP properties.

Example 4: Use an expression as the value of the TemplateContent parameter, save the results in a variable.

This command uses an expression as the value of the TemplateContent parameter. The expression is saved in a variable for simplicity. Windows PowerShell understands now that the string that is used on the pipeline to ConvertFrom-String has three properties:

• Name
• phone
• age

$template = @'
{Name*:Phoebe Cat}, {phone:425-123-6789}, {age:6}
{Name*:Lucky Shot}, {phone:(206) 987-4321}, {age:12}
'@

$testText = @'
Phoebe Cat, 425-123-6789, 6
Lucky Shot, (206) 987-4321, 12
Elephant Wise, 425-888-7766, 87
Wild Shrimp, (111)  222-3333, 1
'@

$PersonalData = $testText | ConvertFrom-String -TemplateContent $template
Write-output ("Pet items found: " + ($PersonalData.Count))
$PersonalData

Pet items found: 4

Name          phone           age
----          -----           ---
Phoebe Cat    425-123-6789    6
Lucky Shot    (206) 987-4321  12
Elephant Wise 425-888-7766    87
Wild Shrimp   (111)  222-3333 1

Each line in the input is evaluated by the sample matches. If the line matches the examples given in the pattern, values are extracted and passed to the output variable.

The sample data, $template, provides two different phone formats:

• 425-123-6789
• (206) 987-4321

The sample data also provides two different age formats:

• 6
• 12

This implies that phones like (206) 987 4321 will not be recognized, because there's no sample data that matches that pattern because there are no hyphens.

Example 5: Specifying data types to the generated properties

This is the same example as Example 4, above. The difference is that the pattern string includes a data type for each desired property.

$template = @'
{[string]Name*:Phoebe Cat}, {[string]phone:425-123-6789}, {[int]age:6}
{[string]Name*:Lucky Shot}, {[string]phone:(206) 987-4321}, {[int]age:12}
'@

$testText = @'
Phoebe Cat, 425-123-6789, 6
Lucky Shot, (206) 987-4321, 12
Elephant Wise, 425-888-7766, 87
Wild Shrimp, (111)  222-3333, 1
'@

$PersonalData = $testText | ConvertFrom-String -TemplateContent $template
Write-output ("Pet items found: " + ($PersonalData.Count))
$PersonalData

Pet items found: 4

Name          phone           age
----          -----           ---
Phoebe Cat    425-123-6789      6
Lucky Shot    (206) 987-4321   12
Elephant Wise 425-888-7766     87
Wild Shrimp   (111)  222-3333   1

$PersonalData | Get-Member

TypeName: System.Management.Automation.PSCustomObject

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
age         NoteProperty int age=6
Name        NoteProperty string Name=Phoebe Cat
phone       NoteProperty string phone=425-123-6789

The Get-Member cmdlet is used to show that the age property is an integer.

Parameters

-Delimiter

-IncludeExtent

-InputObject

-PropertyNames

-TemplateContent

-TemplateFile

-UpdateTemplate

Inputs

String

Outputs

PSCustomObject

Notes

Windows PowerShell includes the following aliases for ConvertFrom-String:

• CFS

Related Links

• ConvertFrom-String: Example-based text parsing
• ConvertFrom-StringData
• ConvertFrom-Csv
• ConvertTo-Xml