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
 

Edit-File

Edit-File

pscx.dll

Synopsis

PSCX Cmdlet: Edits a file using a regex pattern to find text to be replaced by a specified replacement string.

Syntax

Edit-File [-Path] [-PassThru] [<CommonParameters>]

Edit-File [-LiteralPath] [<CommonParameters>]

Edit-File [-Pattern] [-Encoding] [-SimpleMatch] [-SingleString] [<CommonParameters>]

Edit-File [-Replacement] [-CaseSensitive] [-Force] [<CommonParameters>]

Detailed Description

The Edit-File cmdlet modifies the specified files using a search pattern and replacement text. The search pattern is specified by the Pattern parameter and can be either "simple match" text or a regular expression. The replacement text is specified by the Replacement parameter. The Edit-File cmdlet can also be used to edit files interactively. By default, notepad.exe is used to interactively edit the specified file. You can specify an alternate interactive text editor using $Pscx:Preferences['TextEditor] = 'notepad2.exe'. By default the regex is applied to the file line by line. You can use the SingleString parameter to load the entire file into memory as a single string. With SingleString, the regex is applied to the entire file at once. This enables you to specify a regular expression such as '(?s)(<PostBuildEvent>).*?(</PostBuildEvent>)' that spans multiple lines. The regular expression mode modifier '(?s)' enables Singleline mode which causes the '.' metacharacter to match every character including newline characters. One consequence of processing the file using the SingleString parameter is that your regex may have to handle carriage return (\r) characters. The regex metacharacter $ matches only newline (\n) and NOT carriage return (\r) characters. You need to be aware of this when using the metacharacter $ in Multiline mode to replace the entire contents of a line. If you're not careful you can eliminate \r from the newline sequence. To avoid this, use an end of line regex positve look-ahead pattern like '(?=\r$)'.

Parameters

-Path <String[]>

Specifies the path to the file to edit. Wildcard syntax is allowed.

Aliases

None

Required?

true

Position

1

Default value

None

Accept pipeline input?

true (ByValue, ByPropertyName)

Accept wildcard characters?

true

-Pattern <String[]>

Specifies the text to replace. Type a string or regular expression. If you type a string, use the SimpleMatch parameter. To learn about regular expressions, see about_Regular_Expressions.

Aliases

None

Required?

true

Position

2

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-LiteralPath <String[]>

Specifies a path to the file to edit. The value of -LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

Aliases

None

Required?

true

Position

named

Default value

None

Accept pipeline input?

true (ByPropertyName)

Accept wildcard characters?

false

-Replacement <String[]>

The replacement string to use for the specified pattern. You can use regular expression substitutions in the replacement string.

Aliases

None

Required?

true

Position

3

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-CaseSensitive <SwitchParameter>

Makes Pattern matches case-sensitive. By default, Pattern matches are not case-sensitive.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-Encoding <String>

Specifies the type of character encoding used to write to the file. Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". By default, the cmdlet uses the encoding it detected while reading the file. "Default" uses the encoding of the system's current ANSI code page. "OEM" uses the current original equipment manufacturer code page identifier for the operating system.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-Force <SwitchParameter>

Allows the cmdlet to edit files that are read-only by making them writable.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-PassThru <SwitchParameter>

Passes a FileInfo object representing the file to the pipeline. By default, this cmdlet does not generate any output.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-SimpleMatch <SwitchParameter>

Uses a simple match rather than a regular expression match. In a simple match, Edit-File searches the file for the text in the Pattern parameter. It does not interpret the value of the Pattern parameter as a regular expression statement.

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

-SingleString <SwitchParameter>

Processes the file's contents as a single string. By default, the cmdlet processes the file one line at at time. Using SingleString enables regex patterns to select text that spans multiple lines. In order to take take advantage of SingleString you will likely need to use the Singleline mode modifier (?s), Multiline mode modifier (?m) or both (?sm).

Aliases

None

Required?

false

Position

named

Default value

None

Accept pipeline input?

false

Accept wildcard characters?

false

Input Type

System.String

Return Type

None or a System.IO.FileInfo object representing the file.

Notes

Examples

-------------------------- EXAMPLE 1 --------------------------

Starts the editor. Notepad.exe is started unless the PSCX TextEditor preference has been set to another text editor. You can specify an alternate text editor using $Pscx:Preferences['TextEditor] = 'notepad2.exe'

        PS C:\> Edit-File
      

-------------------------- EXAMPLE 2 --------------------------

Starts the text editor passing the specified file to be opened. Notepad.exe is started unless the PSCX TextEditor preference has been set to another text editor. You can specify an alternate text editor using $Pscx:Preferences['TextEditor] = 'notepad2.exe'

        PS C:\> Edit-File $profile
      

-------------------------- EXAMPLE 3 --------------------------

Edits the C# project file replacing v4.0 with v4.5.1

        PS C:\> Edit-File Acme\Src\Foo\Foo.csproj -Pattern v4\.0 -Replacement v4.5.1
      

-------------------------- EXAMPLE 4 --------------------------

Edits all of the C# project files replacing v4.0 with v4.5.1 and making them writable with the Force parameter.

By using the SimpleMatch parameter, you can specify a Pattern that is not interpreted as a regular expression.

        PS C:\> Get-ChildItem Acme\Src\*.csproj -Recurse | Edit-File -Pattern v4.0 -Replacement v4.5.1 -Force -SimpleMatch
      

-------------------------- EXAMPLE 5 --------------------------

Edits all of the C# project files replacing v4.0 with v4.5.1 and making them writable with the Force parameter.

The PassThru switch causes each file to be passed down the pipeline to the Set-ReadOnly command.

        PS C:\> Get-ChildItem Acme\Src\*.csproj -Recurse | Edit-File -Pattern v4\.0 -Replacement v4.5.1 -Force -PassThru | Set-ReadOnly
      

-------------------------- EXAMPLE 6 --------------------------

Edits all of the C# project files effectivly removing all text between the opening and closing PostBuildEvent XML tags.

Specifying the SingleString parameter loads the file into memory as a single string. This enables Singleline mode which causes the '.' metacharacter to match newline (\n) characters. This allows a regex pattern to select text that spans multiple lines.

 PS C:\> $pattern = '(?s)(<PostBuildEvent>).*?(</PostBuildEvent>)'
 PS C:\> Get-ChildItem Acme\Src\*.csproj -Recurse | Edit-File -Pattern $pattern -Replacement '$1$2' -SingleString
      

-------------------------- EXAMPLE 7 --------------------------

The Encoding parameter specifies that the cmdlet writes the file using the specified encoding.

        PS C:\> Edit-File site.css -Pattern '#555\s*;' -Replacement '#5f5f5f;' -Encoding ascii