2024-12-08
F# で Cmdlet を書いてる pt.56
krymtkts/pocof 開発をした。
まだ FsCheck を使った既存の事例テストを PBT で置き換えてる最中。 なるべくシンプルなプロパティにして、ジェネレータでいろんなパターンを書くような感じで今は上手くハマっている。 今はまだ簡単な関数に対するプロパティしか書いてないので、もうそろそろ難易度上げても良い頃合いかも。
.NET 9 のやつも放置状態。 FSharpLint の .NET 9 の問題は issue ができてた。 Latest version incompatible with .NET 9 · Issue #718 · fsprojects/FSharpLint
他に新しいネタとしては、 2024-10-30 に dev blog に出てた PlatyPS の v1 の preview へ移行始めてみた。 調べた内容を整理する意味も込めてまとめておく。
Announcing Microsoft.PowerShell.PlatyPS 1.0.0-Preview1 - PowerShell Team
まだ preview なので PlatyPS のチュートリアルは更新されてない。 Create XML-based help using PlatyPS - PowerShell | Microsoft Learn install は先に挙げた dev blog に従ってやる。
Install-PSResource -Name Microsoft.PowerShell.PlatyPS -Prerelease -Scope AllUsers
> Get-PSResource -Name platyPS,Microsoft.PowerShell.PlatyPS -Scope AllUsers | select Name,Version,PublishedDate
Name Version PublishedDate
---- ------- -------------
platyPS 0.14.2 2021-07-02 22:53:28
Microsoft.PowerShell.PlatyPS 1.0.0 2024-10-29 22:38:53
実に 3 年ぶりの更新になる様子。 pocof を作り始めたときから v0.14.2 を使ってた。
module name も変わった。 PowerShellGet が PSResourceGet になったのと同じ命名規則なので、 PowerShell Team の module は将来皆こうなるんかな。
module に含まれる Function, Cmdlet は随分様変わりした。コレはなるほど使い方がわからん。
> Get-Command -Module platyPS
CommandType Name Version Source
----------- ---- ------- ------
Function Get-HelpPreview 0.14.2 platyPS
Function Get-MarkdownMetadata 0.14.2 platyPS
Function Merge-MarkdownHelp 0.14.2 platyPS
Function New-ExternalHelp 0.14.2 platyPS
Function New-ExternalHelpCab 0.14.2 platyPS
Function New-MarkdownAboutHelp 0.14.2 platyPS
Function New-MarkdownHelp 0.14.2 platyPS
Function New-YamlHelp 0.14.2 platyPS
Function Update-MarkdownHelp 0.14.2 platyPS
Function Update-MarkdownHelpModule 0.14.2 platyPS
> Get-Command -Module Microsoft.PowerShell.PlatyPS
CommandType Name Version Source
----------- ---- ------- ------
Function New-HelpCabinetFile 1.0.0 Microsoft.PowerShell.PlatyPS
Function Show-HelpPreview 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Compare-CommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Export-MamlCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Export-MarkdownCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Export-MarkdownModuleFile 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Export-YamlCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Export-YamlModuleFile 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Import-MamlHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Import-MarkdownCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Import-MarkdownModuleFile 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Import-YamlCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Import-YamlModuleFile 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Measure-PlatyPSMarkdown 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet New-CommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet New-MarkdownCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet New-MarkdownModuleFile 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Test-MarkdownCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Update-CommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Update-MarkdownCommandHelp 1.0.0 Microsoft.PowerShell.PlatyPS
Cmdlet Update-MarkdownModuleFile 1.0.0 Microsoft.PowerShell.PlatyPS
PlatyPS の reference は更新されてるので、そこを参考に手で試しながら理解するしかないか。 Microsoft.PowerShell.PlatyPS Module - PowerShell | Microsoft Learn
pocof の用途だと「既存の help をイイ感じに更新したい」ところなので、その周りの機能を確認する。
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/measure-platypsmarkdown?view=ps-modules
# Markdown help が含む content type と schema version を検証する
# Filetype が enum なので stringify された値に対して match しないと filter できない
# Output の path 属性が Filepath なので pipeline でそのまま渡しにくい
# 気が利いた機能だが出力が微妙に行けてなくて PlatyPS 内での取り回しが良くない
Measure-PlatyPSMarkdown .\docs\*.md
#
# Title Filetype Filepath
# ----- -------- --------
# unknown CommandHelp, V1Schema C:\Users\takatoshi\dev\github.com\krymtkts\pocof\docs\Select-Pocof.md
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/test-markdowncommandhelp?view=ps-modules
# Markdown command help の内容を検査する
Measure-PlatyPSMarkdown .\docs\*.md | ? Filetype -match CommandHelp | select -ExpandProperty FilePath | Test-MarkdownCommandHelp -DetailView
#
# Test-MarkdownCommandHelp
# Valid: True
# File: C:\Users\takatoshi\dev\github.com\krymtkts\pocof\docs\Select-Pocof.md
#
# Messages:
# PASS: First element is a thematic break
# PASS: SYNOPSIS found.
# PASS: SYNOPSIS is in order.
# PASS: SYNTAX found.
# PASS: SYNTAX is in order.
# PASS: DESCRIPTION found.
# PASS: DESCRIPTION is in order.
# PASS: EXAMPLES found.
# PASS: EXAMPLES is in order.
# PASS: PARAMETERS found.
# PASS: PARAMETERS is in order.
# PASS: INPUTS found.
# PASS: INPUTS is in order.
# PASS: OUTPUTS found.
# PASS: OUTPUTS is in order.
# PASS: NOTES found.
# PASS: NOTES is in order.
# PASS: RELATED LINKS found.
# PASS: RELATED LINKS is in order.
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/import-markdowncommandhelp?view=ps-modules
# Markdown command help を読み込んで command help の object を作る
$before = Measure-PlatyPSMarkdown .\docs\*.md | ? Filetype -match CommandHelp | select -ExpandProperty FilePath | Import-MarkdownCommandHelp
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/update-commandhelp?view=ps-modules
# command help object を session に存在する同名 cmdlet の情報で更新する
$after = Measure-PlatyPSMarkdown .\docs\*.md | ? Filetype -match CommandHelp | select -ExpandProperty FilePath | Update-CommandHelp
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/compare-commandhelp?view=ps-modules
# command help object 同士を比較した text を出力する
# 出力される text が D=delete, M=modified, S=same ぽいので適宜 filter しないといけない
Compare-CommandHelp $before $after | ? {$_ -notlike 'S*'}
# M Inspecting dictionary CommandHelp.Metadata
# D CommandHelp.Metadata: ms.date does not exist in reference
# M Inspecting list CommandHelp.Syntax
# D CommandHelp.Syntax lists are different sizes (1 vs 2)
# 省略
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/export-markdowncommandhelp?view=ps-modules
# command help object を Markdown command help に出力する
# OutputFolder 配下に module name で directory が作成されてその中に出力される
# module name の directory 作らず平置きしてる場合は注意
$after | Export-MarkdownCommandHelp -OutputFolder .\docs
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/update-markdowncommandhelp?view=ps-modules
# Markdown command help を session に存在する同名 cmdlet の情報で更新する
# デフォ *.bak ファイルを作ってくるので、 -NoBackup を指定すると作らなくなる
# description とか example に手で書いた内容は消えないので気軽に実行できる
Measure-PlatyPSMarkdown .\docs\*.md | ? Filetype -match CommandHelp | select -ExpandProperty FilePath | Update-MarkdownCommandHelp -NoBackup
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/export-mamlcommandhelp?view=ps-modules
# OutputFolder 配下に module name で directory が作成されてその中に `${moduleName}-Help.xml` 出力される
Measure-PlatyPSMarkdown .\docs\*.md | ? Filetype -match CommandHelp | select -ExpandProperty FilePath | Import-MarkdownCommandHelp | Export-MamlCommandHelp -OutputFolder ./src/
# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/show-helppreview?view=ps-modules
# 出力した MAML を Markdown preview する。何故かこいつは Path が Position 0 じゃなく Named なので注意
Show-HelpPreview -Path .\src\pocof\pocof-Help.xml
# 省略
Measure-PlatyPSMarkdown の output の object が pipeline で使いにくいのだけ気に入らんが、他は良好な使用感そう。
pocof の古いドキュメントを更新するにあたってやるべきことも見えてきた。
Update-MarkdownCommandHelp を 0.14.2 で作った Markdown command help に対して実行すると scheme の version が 1 -> 2 になって結構変わるので、初回は scheme の更新のみで実行する方が良さそう。
OutputFolder 配下に module name の directory ができるのもあるし、出力されるファイル名が変わるのもあるし、まずは今の構造を変えるのが良さげやな。
あと地味に Markdown の table が MAML 翻訳されない bug も直ってるようなので、コレを気に pocof の help も多少綺麗にできるかな。 Markdown tables not rendered properly in MAML · Issue #577 · PowerShell/platyPS
続く。