Bulk rename¶
Rename many files with find/replace, a live preview, a confirmation dialog and undo.
Same example in Python: Bulk rename

Real capture on KDE Plasma 6.6 Wayland with the released packages.
What it teaches: Open-NativeHTMLKitFile with index.html and style.css; pure planning logic; live preview; folder dialog fallback; undo.
Run it¶
pwsh -File bulk-rename/app.ps1
Related guide: project scaffolding
Source: bulk-rename/app.ps1¶
# bulk-rename/app.ps1 - rename many files with find/replace, a live preview and undo.
# This is the finished app of the tutorial docs/tutorials/bulk-rename.md.
#
# Teaches: an app split into index.html + style.css + app.ps1 (Open-NativeHTMLKitFile),
# a pure planning function that is easy to test, live preview on input events, the native
# folder picker with a capability fallback, a confirmation <dialog>, per-file error
# handling, and undo.
#
# Run: pwsh -File ./app.ps1 [-Folder C:\Photos]
# powershell.exe -NoProfile -File .\app.ps1
# -SelfTest renames files in a temporary folder, undoes it, and quits.
param([string]$Folder, [switch]$SelfTest)
$ErrorActionPreference = 'Stop'
Import-Module NativeHTMLKit
# ---------------------------------------------------------------- planning (no UI) --
function Get-RenamePlan {
# Returns one row per file: Old, New, Status (unchanged | rename | conflict | invalid | error), Note.
param([string[]]$Names, [string]$Find, [string]$Replace, [bool]$Regex, [bool]$MatchCase)
$options = [Text.RegularExpressions.RegexOptions]::None
if (-not $MatchCase) { $options = [Text.RegularExpressions.RegexOptions]::IgnoreCase }
$pattern = $Find
$replacement = $Replace
if (-not $Regex) {
$pattern = [regex]::Escape($Find)
$replacement = $Replace.Replace('$', '$$') # literal text, not $1 group references
}
$matcher = $null
$patternError = $null
if ($Find) {
try { $matcher = New-Object Text.RegularExpressions.Regex($pattern, $options) }
catch {
$reason = $_.Exception
if ($null -ne $reason.InnerException) { $reason = $reason.InnerException }
$patternError = 'Invalid pattern: ' + $reason.Message
}
}
$comparer = [StringComparer]::Ordinal
if ([Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT) { $comparer = [StringComparer]::OrdinalIgnoreCase }
$existing = New-Object 'System.Collections.Generic.HashSet[string]' -ArgumentList @(, $comparer)
foreach ($name in $Names) { [void]$existing.Add($name) }
$claimed = New-Object 'System.Collections.Generic.HashSet[string]' -ArgumentList @(, $comparer)
$invalid = [IO.Path]::GetInvalidFileNameChars()
foreach ($name in $Names) {
$row = [pscustomobject]@{ Old = $name; New = $name; Status = 'unchanged'; Note = '' }
if ($patternError) { $row.Status = 'error'; $row.Note = $patternError }
elseif ($null -ne $matcher) {
$new = $matcher.Replace($name, $replacement)
$row.New = $new
if ($new -cne $name) {
if (-not $new -or $new.IndexOfAny($invalid) -ge 0 -or $new -eq '.' -or $new -eq '..') { $row.Status = 'invalid'; $row.Note = 'Not a valid file name' }
elseif (($existing.Contains($new) -and -not $comparer.Equals($new, $name)) -or -not $claimed.Add($new)) { $row.Status = 'conflict'; $row.Note = 'Name already used' }
else { $row.Status = 'rename' }
}
}
$row
}
}
# --------------------------------------------------------------------- the app --
$app = Start-NativeHTMLKitScript -Name 'Bulk rename'
$selfTestFolder = $null
try {
if ($SelfTest) {
$selfTestFolder = Join-Path ([IO.Path]::GetTempPath()) ('nhk-rename-' + [guid]::NewGuid().ToString('N'))
$null = New-Item -ItemType Directory -Path $selfTestFolder
foreach ($n in 'IMG_0001.jpg', 'IMG_0002.jpg', 'img_0003.JPG', 'notes.txt', 'holiday_0001.jpg') { [IO.File]::WriteAllText((Join-Path $selfTestFolder $n), $n) }
$Folder = $selfTestFolder
}
$window = New-NativeHTMLKitWindow -Application $app -Title 'Bulk rename' -Width 900 -Height 620 -MinWidth 640 -MinHeight 400
# Relative URLs in index.html (style.css) resolve against the file's folder.
$doc = Open-NativeHTMLKitFile -Window $window -Path (Join-Path $PSScriptRoot 'index.html')
$state = @{ Folder = $null; Names = @(); Plan = @(); Undo = @() }
$caps = Get-NativeHTMLKitCapabilities -Application $app
if (-not $caps.file_dialogs) { Set-NativeHTMLKitDocumentAttribute -Document $doc -Element browse -Name disabled }
function Read-Rule {
return @{
Find = Get-NativeHTMLKitValue -Document $doc -Element find
Replace = Get-NativeHTMLKitValue -Document $doc -Element replace
Regex = Get-NativeHTMLKitChecked -Document $doc -Element regex
MatchCase = Get-NativeHTMLKitChecked -Document $doc -Element case
}
}
function Update-Preview {
$rule = Read-Rule
$state.Plan = @(Get-RenamePlan -Names $state.Names -Find $rule.Find -Replace $rule.Replace -Regex $rule.Regex -MatchCase $rule.MatchCase)
$html = New-Object System.Text.StringBuilder
foreach ($row in $state.Plan) {
$status = $row.Status
if ($row.Note) { $status = $row.Note }
[void]$html.Append("<tr class=`"$($row.Status)`"><td>" + [Net.WebUtility]::HtmlEncode($row.Old) + '</td><td>' +
[Net.WebUtility]::HtmlEncode($row.New) + '</td><td>' + [Net.WebUtility]::HtmlEncode($status) + '</td></tr>')
}
Set-NativeHTMLKitDocumentHtml -Document $doc -Element preview -Html $html.ToString()
$count = @($state.Plan | Where-Object { $_.Status -eq 'rename' }).Count
$blocked = @($state.Plan | Where-Object { $_.Status -in 'conflict', 'invalid', 'error' }).Count
$summary = "$($state.Names.Count) file(s), $count to rename"
if ($blocked) { $summary += ", $blocked skipped" }
Set-NativeHTMLKitDocumentText -Document $doc -Element summary -Text $summary
Set-NativeHTMLKitDocumentText -Document $doc -Element apply -Text "Rename $count"
if ($count -gt 0) { Set-NativeHTMLKitDocumentAttribute -Document $doc -Element apply -Name disabled -Remove }
else { Set-NativeHTMLKitDocumentAttribute -Document $doc -Element apply -Name disabled }
}
function Update-FileList {
$state.Names = @(Get-ChildItem -LiteralPath $state.Folder -File | Sort-Object Name | ForEach-Object { $_.Name })
Update-Preview
}
function Open-Folder([string]$Path) {
if (-not $Path -or -not (Test-Path -LiteralPath $Path -PathType Container)) {
Set-NativeHTMLKitDocumentText -Document $doc -Element summary -Text 'That folder does not exist.'
return
}
$state.Folder = (Resolve-Path -LiteralPath $Path).ProviderPath
Set-NativeHTMLKitDocumentValue -Document $doc -Element folder -Value $state.Folder
Set-Undo @()
Update-FileList
}
function Set-Undo($Steps) {
$state.Undo = @($Steps)
if ($state.Undo.Count -gt 0) { Set-NativeHTMLKitDocumentAttribute -Document $doc -Element undo -Name disabled -Remove }
else { Set-NativeHTMLKitDocumentAttribute -Document $doc -Element undo -Name disabled }
}
function Invoke-Rename {
$done = New-Object System.Collections.ArrayList
$failed = 0
foreach ($row in @($state.Plan | Where-Object { $_.Status -eq 'rename' })) {
try {
Rename-Item -LiteralPath (Join-Path $state.Folder $row.Old) -NewName $row.New
[void]$done.Add(@{ From = $row.Old; To = $row.New })
} catch { $failed++ } # in use, permission denied, or changed since the preview
}
Set-Undo $done.ToArray()
Update-FileList
$message = "Renamed $($done.Count) file(s)."
if ($failed) { $message += " $failed failed (in use, permission denied or changed)." }
Set-NativeHTMLKitDocumentText -Document $doc -Element summary -Text $message
}
function Undo-Rename {
if ($state.Undo.Count -eq 0) { return }
$restored = 0
# Reverse order, so chains such as a->b, b->c are undone correctly.
foreach ($step in $state.Undo[($state.Undo.Count - 1)..0]) {
try { Rename-Item -LiteralPath (Join-Path $state.Folder $step.To) -NewName $step.From; $restored++ } catch { $null = $_ }
}
Set-Undo @()
Update-FileList
Set-NativeHTMLKitDocumentText -Document $doc -Element summary -Text "Restored $restored file name(s)."
}
function Confirm-Rename([bool]$Yes) {
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm -Close -ReturnValue ''
if ($Yes) { Invoke-Rename }
}
# Live preview: every keystroke or checkbox change in the rule form.
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type input -Element rule -Callback { Update-Preview }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type change -Element rule -Callback { Update-Preview }
# Enter in a rule field submits the form: treat it as "update preview", nothing else.
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type submit -Element rule -Callback { Update-Preview }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element load -Callback { Open-Folder (Get-NativeHTMLKitValue -Document $doc -Element folder) }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element browse -Callback {
try { $picked = Show-NativeHTMLKitFileDialog -Window $window -Kind ChooseFolder -Title 'Folder with files to rename' }
catch [NativeHTMLKit.RpcException] { Set-NativeHTMLKitDocumentText -Document $doc -Element summary -Text $_.Exception.RpcMessage; return }
if (-not $picked.cancelled) { Open-Folder @($picked.paths)[0] }
}
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element apply -Callback {
$count = @($state.Plan | Where-Object { $_.Status -eq 'rename' }).Count
Set-NativeHTMLKitDocumentText -Document $doc -Element confirm-text -Text "Rename $count file(s) in $($state.Folder)?"
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm
}
# Decide in the button handlers, not in the dialog's close event: a <dialog> keeps its
# previous return value when the user dismisses it with Escape.
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element confirm-no -Callback { Confirm-Rename $false }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element confirm-yes -Callback { Confirm-Rename $true }
$null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element undo -Callback { Undo-Rename }
if ($Folder) { Open-Folder $Folder }
Set-NativeHTMLKitReady -Application $app
if ($SelfTest) {
Set-NativeHTMLKitDocumentValue -Document $doc -Element find -Value '^img_(\d+)'
Set-NativeHTMLKitDocumentValue -Document $doc -Element replace -Value 'photo-$1'
Set-NativeHTMLKitChecked -Document $doc -Element regex -Checked $true
Update-Preview
if ((Get-NativeHTMLKitDocumentText -Document $doc -Element summary) -ne '5 file(s), 3 to rename') { throw 'unexpected regex preview' }
Set-NativeHTMLKitChecked -Document $doc -Element case -Checked $true
Update-Preview
if ((Get-NativeHTMLKitDocumentText -Document $doc -Element summary) -ne '5 file(s), 1 to rename') { throw 'match case not applied' }
Set-NativeHTMLKitDocumentValue -Document $doc -Element find -Value '('
Update-Preview
if ((Find-NativeHTMLKitElement -Document $doc -Selector '#preview tr.error').matched_nodes -ne 5) { throw 'invalid pattern not reported' }
# Literal mode: '0001' -> 'notes' clashes with nothing, but two files would get the same name.
Set-NativeHTMLKitChecked -Document $doc -Element regex -Checked $false
Set-NativeHTMLKitChecked -Document $doc -Element case -Checked $false
Set-NativeHTMLKitDocumentValue -Document $doc -Element find -Value 'holiday'
Set-NativeHTMLKitDocumentValue -Document $doc -Element replace -Value 'IMG'
Update-Preview
if ((Find-NativeHTMLKitElement -Document $doc -Selector '#preview tr.conflict').matched_nodes -ne 1) { throw 'conflict not detected' }
Set-NativeHTMLKitDocumentValue -Document $doc -Element find -Value 'IMG_'
Set-NativeHTMLKitDocumentValue -Document $doc -Element replace -Value '2026 $ '
Update-Preview
# The confirm path: the dialog opens, the user picks "Rename".
Show-NativeHTMLKitHtmlDialog -Document $doc -Element confirm
Confirm-Rename $true
if ((Invoke-NativeHTMLKitDocumentCommand -Document $doc -Operation get_dialog -Parameters @{ element = 'confirm' }).open) { throw 'dialog still open' }
$names = @(Get-ChildItem -LiteralPath $selfTestFolder -File | ForEach-Object { $_.Name } | Sort-Object)
if (-not ($names -contains '2026 $ 0001.jpg') -or -not ($names -contains '2026 $ 0003.JPG')) { throw "rename failed: $($names -join ', ')" }
Undo-Rename
if ((Get-NativeHTMLKitDocumentText -Document $doc -Element summary) -ne 'Restored 3 file name(s).') { throw 'undo failed' }
if (-not (Test-Path -LiteralPath (Join-Path $selfTestFolder 'img_0003.JPG'))) { throw 'original name not restored' }
[Console]::Out.WriteLine('SELFTEST PASS bulk-rename')
$null = Request-NativeHTMLKitQuit -Application $app
}
Wait-NativeHTMLKit -Application $app -UntilShutdown
} finally {
Close-NativeHTMLKit -Application $app
if ($selfTestFolder) { Remove-Item -LiteralPath $selfTestFolder -Recurse -Force -ErrorAction SilentlyContinue }
}