PowerShell 7 で GUI（WinForms）を使って、Markdown Viewer/Editor を作ってみた。

機能

Editor 部

• 基本的にはただの TextBox
• Live editor として機能
• 外部からファイルのドラッグ＆ドロップ可能
  • *.md なら、そのファイルを開く
  • 画像(*.(png|gif|jpe?g|webp|svg)) ファイルなら、カーソル位置へ ![](file:///...) を挿入

Browser 部

• HTMLレンダリングには WebView2 を使用
• GitHub Markdown 的なCSS
• 外部からファイルのドラッグ＆ドロップ可能
  • *.md なら、そのファイルを開く

HTMLレンダリング

起動すると MDView.html が読み込まれる。

エディタ部分のmarkdownテキストは PowerShell 7 内臓の ConvertFrom-Markdown (markdig)で HTML に変換され、MDView.html 内の JavaScript 関数に渡される。

コードブロックのハイライトとコピーのために、highlight.js と highlightjs-copy を読み込むようにしている。

この辺りや CSS が気に入らなければ、好きに弄ってくれ。

Fileメニュー

特に言うこと無し

Viewメニュー

• TopMost: ウィンドウを常に全面に出すやつ
• SplitView: エディタ部分とブラウザ部分を両方表示
• Editor Only: エディタ部分のみ表示
• Browser Only: ブラウザ部分のみ表示
• Preview Mode:
  • ファイルの更新監視をして、ブラウザへ反映させる
  • ファイルを開いている時のみ有効
  • 好きなエディタでMarkdownファイルを開いて更新してね
• Font: エディタ部分のフォントを変更

セットアップ

PowerShell 7 以上(Windows標準でインストールされているPowerShell 5.1ではない)で https://github.com/teramako/PSMarkdownEditor/blob/main/setup.ps1 を実行してもらう。

pwsh -NoProfile -File path\to\setup.ps1

実行すると setup.ps1 があるディレクトリに以下を行う

1. WebView2 のセットアップ
   • WebView2 が使用するデータ保管用ディレクトリ(webview2_userdata)
   • .NET 用ライブラリを www.nuget.org からダウンロード
   • ダウンロードしたファイル(zip形式)中から必要な dll ファイルを libs ディレクトリに展開
2. 起動用ショートカット(MDView.lnk)の作成
   • conhost.exe --headless 経由でスクリプト(ps1)実行することで、コマンドプロンプトが一瞬表示されるのを防止

あとは、MDView.lnk を実行すれば起動する

苦労話とか開発Tips

System.Windows.Forms.Form を継承したクラス作成

当初、普通に C# で書くような感じで、System.Windows.Forms.Form を継承したクラスを作って使用しようと、以下のように書いた。

using namespace System.Windows.Forms;
using namespace System.Drawing;
using namespace Microsoft.Web.WebView2.Core;
using namespace Microsoft.Web.WebView2.WinForms;

# ..

Add-Type -AssemblyName System.Windows.Forms;
Add-Type -AssemblyName System.Drawing;
Add-Type -Path $PSScriptRoot\libs\Microsoft.Web.WebView2.Core.dll
Add-Type -Path $PSScriptRoot\libs\Microsoft.Web.WebView2.WinForms.dll

class MDView : Forms {
    # ...
}

ところが、これではうまく行かない。

Add-Type による dll 読み込みより先にクラス定義が読み込まれてしまうのだ。 アセンブリ参照が足りない、みたいなエラーになって怒られる。

そこで、2ファイルに分ける対応をした。

MDView.ps1:

Add-Type -AssemblyName System.Windows.Forms;
Add-Type -AssemblyName System.Drawing;
Add-Type -Path $PSScriptRoot\libs\Microsoft.Web.WebView2.Core.dll
Add-Type -Path $PSScriptRoot\libs\Microsoft.Web.WebView2.WinForms.dll

. (Join-Path $PSScriptRoot MDView.class.ps1)

MDView.class.ps1:

using namespace System.Windows.Forms;
using namespace System.Drawing;
using namespace Microsoft.Web.WebView2.Core;
using namespace Microsoft.Web.WebView2.WinForms;

class MDView : Forms {
    # ...
}

このように Add-Type → クラス定義 の順番を強制することで、PowerShell でも問題なく Form を継承したクラスを作れる。

Timer による遅延レンダリング

TextBox の TextChanged イベント発生毎に HTML レンダリングしていると重たくなる。

そこで System.Windows.Forms.Timer を使用して、 一定時間入力が止まったらレンダリング する方式にした。

class MDView : Form {
    [Timer] $UpdateTimer
    [TextBox] $MarkdownTextBox
    MDView() {
        $this.UpdateTimer = New-Object Timer -Property @{ Interval = 500 }
        $this.MarkdownTextBox = New-Object TextBox -Property @{ ... }
    }

    [void] Form_Load($s, $e) {
        $this.MarkdownTextBox.Add_TextChanged($this.MarkdownTextBox_TextChanged)
        $this.UpdateTimer.Add_Tick($this.UpdateTimer_Tick)
    }

    [void] MarkdownTextBox_TextChanged($s, $e) {
        $this.UpdateTimer.Stop();
        $this.UpdateTimer.Start();
    }

    [void] UpdateTimer_Tick($s, $e) {
        $this.UpdateTimer.Stop();
        $this.UpdateView($null) # ←ブラウザにHTMLレンダリングさせるメソッド
    }

TextChanged イベント発生時には Timer の停止、開始のみ行い、 Timer に設定された Interval (ミリ秒) 経過後に実際のHTMLレンダリングをさせる。

ファイル監視

好きなエディタで書いて保存すると自動でブラウザに反映させたくてファイル監視機能を付けようとした。

System.IO.FileSystemWather を使用したのだが、最初は PowerShell がクラッシュしてしまった。

原因は、イベントが UI スレッドではなく ThreadPool スレッドで発火するため だそうで、PowerShell のコードが実行できず例外になる。

解決策は SynchronizingObject を設定すること。

$fsw = [IO.FileSystemWatcher]::new($this.File.DirectoryName, $this.File.Name)
$fsw.NotifyFilter = [IO.NotifyFilters]::LastWrite;
$fsw.IncludeSubdirectories = $false;
$fsw.SynchronizingObject = $this; # ← UIスレッドでイベントを発行させる
$fsw.EnableRaisingEvents = $true;
$fsw.Add_Changed($this.FileWatcher_Changed)

WebView2 へのファイルのドラッグ＆ドロップ

ブラウザ部分へ *.md ファイルをドロップすることで、そのファイルをHTMLレンダリングさせようとした。 通常なら DragEnter や DragDrop イベントをハンドラを設定するのだが、 WebView2 では NewWindowRequested イベントが発行される仕様なようで、このイベントのハンドラを設置する必要がある。

$this.WebView.CoreWebView2.Add_NewWindowRequested($this.WebView_NewWindowRequested)

[void] WebView_NewWindowRequested($s, [CoreWebView2NewWindowRequestedEventArgs] $e) {
    $uri = [uri]::new($e.Uri)
    if ($uri.IsFile) {
        $e.Handled = $true
        $fileInfo = [IO.FileInfo]::new($uri.LocalPath)
        if ($fileInfo.Extension -eq ".md") {
            $this.TryOpenMarkdownFile($fileInfo)
        }
    }
}

Set-Alias ls 'ls --color -F'

とかができない。

ということで、多少制限があるものの可能にするものを作った。

• https://github.com/teramako/PSApplicationAlias

使用方法

プロファイルに dot-source でスクリプトを読み込む形で使う。

. $PSScriptRoot\AppAlias.ps1

読み込むと、Set-ApplicationAlias というコマンド（関数）が使えるようになる。

# Remove built-in alias (AllScope) before redefining
Remove-Item Alias:ls, Alias:cat

Set-ApplicationAlias cat D:\Program\Git\usr\bin\cat.exe

# If the command is a path that contains spaces, set it in the format `& "Command Name" ...`.
Set-ApplicationAlias ls '& "C:\Program Files\coreutils\bin\ls.exe" --color -F'

定義済みのエイリアス削除して(※)、Set-ApplicationAlias でエイリアス設定をする。

※: PowerShell の組み込み alias（ls, cat, dir など）は AllScope で定義されていて、対話セッション中に Set-Alias で上書きできない。PROFILE 内で Remove-Item しておく必要がある。

内部動作

Set-ApplicationAlias 内部では PowerShell 本体の Set-Alias を呼んでエイリアス定義をしているが、Description プロパティに JSON 形式でコマンドパスと引数リストを埋め込んでいる。 そして、実行先の Invoke-AliasApplication という(dot-source で読み込んだスクリプト内で定義している)関数を固定的に設置している。

Set-Alias -Name $Name -Value Invoke-AliasApplication -Description $json -Scope Global

> Get-Alias -Definition Invoke-AliasApplication | select CommandType,DisplayName,Description

CommandType DisplayName                    Description
----------- -----------                    -----------
      Alias cat -> Invoke-AliasApplication {"Command":"D:\\Program\\Git\\usr\\bin\\cat.exe","Args":{}}
      Alias ls -> Invoke-AliasApplication  {"Command":"C:\\Program Files\\coreutils\\bin\\ls.exe","Args":["--color","-F"]}

※: Get-ApplicationAlias で上記と同等の結果が得られるようなコマンドもあるよ

cat や ls を実行すると、Invoke-AliasApplication が呼ばれる。

Invoke-AliasApplication 内では、実行元となったエイリアス名を取得し、そのエイリアスのDescriptionプロパティからコマンドパスと引数リストを得る。 あとは、パイプライン入力値と共にコマンドに引数を付けて実行する。

コード自体は、割と単純だ。

function Invoke-AliasApplication {
    begin {
        $aliasName = $MyInvocation.InvocationName
        if ($aliasName -eq $MyInvocation.MyCommand.Name) {
            throw "Don't call this function directly."
        }

        $alias = Get-Alias $aliasName
        $info = $alias.Description | ConvertFrom-Json
        $cmdName = $info.Command
        $cmdArgs = $info.Args

        if (-not $cmdName) {
            throw ("Description of '{0}' may be incorrect: {1}" -f $aliasName, $alias.Description);
        }
    }
    end {
        $input | & $cmdName @cmdArgs @args
    }
}

ポイントは、実行元となったエイリアス名の取得するところ。

$aliasName = $MyInvocation.InvocationName

元々、$MyInvocation.InvocationName で Unix系の $0 に似ているものが取れて面白いことができそうだと目を付けていたのが今回役に立った。

制限: バイナリ入出力不可

• バイナリデータが欲しい時には、この方法でのエイリアス設定はしない方が良い。

まず、PowerShell 本体の動きの話から。

通常の Cmdlet や関数のパイプライン入出力は、その型のオブジェクトになる。 対して、外部コマンド1 | 外部コマンド2 のような外部コマンドのパイプ間や、外部コマンド > file のような外部コマンドのリダイレクトでは、外部コマンド同士の世界に閉じられるためパイプライン入出力がバイナリ・ストリーム直で行われるようになっている。 そして、外部コマンドと PowerShell のCmdletや関数、式が混在すると、バイナリ・ストリームは文字列(string[])化されて PowerShell とのやり取りが行われる。

で、エイリアス設定すると PowerShell の関数でラップされるので、外部コマンド1 | 外部コマンド2 のように見えてもバイナリ・ストリームでの入出力が行われず、文字列での入出力になってしまう。

文字コードや改行コードが変わったりするため、以下のような違いが出てしまう。

> Get-Command cat

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Alias           cat -> Invoke-AliasApplication

> sha1sum .\shift_jis.txt
46f0ea63e867da29af52457ea9e465af03dbb60b  ./shift_jis.txt
> D:\Program\Git\usr\bin\cat.exe .\shift_jis.txt | sha1sum
46f0ea63e867da29af52457ea9e465af03dbb60b  -
> cat .\shift_jis.txt | sha1sum
471399aeda50586bdc982b558bfde1da642c0fb3  -

cat を ApplicationAlias でラップすると PowerShell の関数として実行されるため、 外部コマンド間のバイナリストリームではなく、文字列化されたパイプラインが流れる。その結果、文字コード変換や改行変換が入り、ハッシュ値が変わってしまう。

制限: Cmdletには使えない

• 外部コマンドのエイリアス設定にしか使えない

Cmdlet のパラメーターは string[] な配列ではなく、ディクショナリ(Hashtable) で設定する必要があったり、パラメーター値も文字列とは限らないなど、複雑なので今回は外部コマンドのみに限定した。

Cmdlet の場合のパラメーター値設定は $PSDefaultParameterValues (about_Parameters_Default_Values - PowerShell | Microsoft Learn) を使った方が良いだろうし。

• https://github.com/JustinGrote/ExcelFast/blob/main/Source/PowerShell/Cmdlets/TaskCmdlet.cs

某所で紹介されていて、感動したので肝の部分を解説したい。

Sashimi では、この方式を応用して、外部プロセスの stdout/stderr を非同期で読み取りつつ、 Cmdlet スレッド側でリアルタイムに出力する仕組みを構築している。

Cmdlet は非同期出力不可

PowerShell の Cmdlet は同期的に動く。

1. Begin (BeginProcessing) で初期化
2. Process (ProcessRecord) でパイプライン入力処理
3. End (EndProcessing) で最終的な処理

のような流れで、PowerShell 本体から呼び出される。

各処理で非同期処理も可能ではあるものの、出力処理（WriteObject とか WriteError とか）はそのCmdletのメインスレッドからしか実行できない制約がある。

[Cmdlet(VerbsDiagnostic.Test, "AsyncCmd")]
public class TestAsyncCommand : PSCmdlet
{
    [Parameter()]
    public string Message { get; set; } = "Hello";

    private Task? _outputTask;
    private Stopwatch _sw = Stopwatch.StartNew();

    protected override void BeginProcessing()
    {
        WriteVerbose($"({_sw.Elapsed}) Start: BeginProcessing");
        _outputTask = Task.Run(OutputAsync);
        WriteVerbose($"({_sw.Elapsed}) End: BeginProcessing");
    }
    protected override void EndProcessing()
    {
        WriteVerbose($"({_sw.Elapsed}) Start: EndProcessing");
        try
        {
            _outputTask?.Wait();
        }
        catch (AggregateException ex)
        {
            WriteError(new(ex.InnerException, "AsyncError", ErrorCategory.NotSpecified, this));
        }
        WriteVerbose($"({_sw.Elapsed}) End: EndProcessing");
    }

    private async Task OutputAsync()
    {
        for (var i = 0; i < 10; i++)
        {
            WriteObject($"({_sw.Elapsed}) {Message}");
            await Task.Delay(100);
        }
    }
}

上記のように、 BeginProcessing 内で非同期処理を走らせ、EndProcessing で終了を待とうとするとエラーになる。

Test-AsyncCmd: The WriteObject and WriteError methods cannot be called from outside the overrides of the BeginProcessing, ProcessRecord,
and EndProcessing methods, and they can only be called from within the same thread.
Validate that the cmdlet makes these calls correctly, or contact Microsoft Customer Support Services.

PowerShell の WriteObject は内部で「呼び出し元スレッド ID」を検証しており、Cmdlet 実行スレッド以外からの呼び出しを明確に禁止しているのだ。 出力系メソッドは、メインスレッドから呼び出さなくてはならない。

どうするか？

出力させたいものはキューに貯めて、後で出力する。

修正案

以下のようになる。

using System.Collections.Concurrent;
using System.Diagnostics;
using System.Management.Automation;

[Cmdlet(VerbsDiagnostic.Test, "AsyncCmd")]
public class TestAsyncCommand : PSCmdlet
{
    [Parameter()]
    public string Message { get; set; } = "Hello";

    private enum RecordType { Output, Error, Warning, Verbose, Debug, Information }
    private readonly record struct OutputRecord(RecordType Type, object Value);

    private BlockingCollection<OutputRecord> _outputs = new();
    private Task? _outputTask;
    private Stopwatch _sw = Stopwatch.StartNew();

    protected override void BeginProcessing()
    {
        _outputs.Add(new(RecordType.Verbose, $"({_sw.Elapsed}) Start: BeginProcessing"));
        _outputTask = Task.Run(OutputAsync);
        _outputs.Add(new(RecordType.Verbose, $"({_sw.Elapsed}) End: BeginProcessing"));
    }
    protected override void EndProcessing()
    {
        _outputs.Add(new(RecordType.Verbose, $"({_sw.Elapsed}) Start: EndProcessing"));

        Task _completedTask = Task.Run(async () =>
        {
            try
            {
                await _outputTask;
            }
            finally
            {
                _outputs.CompleteAdding();
            }
        });

        foreach (var record in _outputs.GetConsumingEnumerable())
        {
            switch (record.Type)
            {
                case RecordType.Output:
                    WriteObject(record.Value);
                    break;
                case RecordType.Error:
                    if (record.Value is ErrorRecord err)
                        WriteError(err);
                    else if (record.Value is Exception ex)
                        WriteError(new ErrorRecord(ex, "CmdletError", ErrorCategory.NotSpecified, this));
                    break;
                case RecordType.Warning:
                    WriteWarning($"{record.Value}");
                    break;
                case RecordType.Verbose:
                    WriteVerbose($"{record.Value}");
                    break;
                case RecordType.Debug:
                    WriteDebug($"{record.Value}");
                    break;
                case RecordType.Information:
                    if (record.Value is InformationRecord info)
                        WriteInformation(info);
                    else
                        WriteInformation(record.Value, []);
                    break;
            }
        }
        try
        {
            _completedTask.Wait();
        }
        catch (AggregateException ex)
        {
            WriteError(new(ex.InnerException, "AsyncError", ErrorCategory.NotSpecified, this));
        }
        finally
        {
            _outputs.Dispose();
        }
        WriteVerbose($"({_sw.Elapsed}) End: EndProcessing");
    }

    private async Task OutputAsync()
    {
        for (var i = 0; i < 10; i++)
        {
            _outputs.Add(new OutputRecord(RecordType.Output, $"({_sw.Elapsed}) {Message}"));
            await Task.Delay(100);
        }
    }
}

解説

キューにはスレッドセーフな BlockingCollection<T> を使用するのが肝。

    private BlockingCollection<OutputRecord> _outputs = new();

非同期メソッド内では、この _output に追加していく。

キューに貯める「生産者」を別スレッド、溜まったオブジェクトを使用する「消費者」を Cmdletのスレッドにするのだ。

スレッドセーフなキューとして、ConcurrentQueue<T> があるが、ただ TryDequeue() していくだけだと空になった後に追加で溜まるかもしれないものを待つのに別実装が必要になる。 対して BlockingCollection<T> は GetConsumingEnumerable() メソッドで生産完了フラグが立つまで待つことができるのだ。

    protected override void EndProcessing()
    {
        // キュー生産者側を別スレッドで
        Task _completedTask = Task.Run(async () =>
        {
            try
            {
                await _outputTask;
            }
            finally
            {
                _outputs.CompleteAdding();
            }
        });

        // キューの消費者側は Cmdlet のスレッドで
        foreach (var record in _outputs.GetConsumingEnumerable())
        {
            // WriteObject() 等
        }

        // 最後の終了処理
        try
        {
            _completedTask.Wait();
        }
        catch (AggregateException ex)
        {
            WriteError(new(ex.InnerException, "AsyncError", ErrorCategory.NotSpecified, this));
        }
        finally
        {
            _outputs.Dispose();
        }
    }

_outputs.GetConsumingEnumerable() 中は生産完了フラグが立つまで完全に待ちになるので、別スレッドから出力タスクの完了と _outputs.CompleteAdding() による生産完了通知をする必要がある点に注意。

また、溜め込むオブジェクトは WriteObject, WriteError, WriteWarning 等、どのストリームに出力するか区別できるようにしておくと、良い。

    private enum RecordType { Output, Error, Warning, Verbose, Debug, Information }
    private readonly record struct OutputRecord(RecordType Type, object Value);

        foreach (var record in _outputs.GetConsumingEnumerable())
        {
            switch (record.Type)
            {
                case RecordType.Output:
                    WriteObject(record.Value);
                    break;
                case RecordType.Error:
                    WriteError(...);
                    break;
                case RecordType.Warning:
                    WriteWarning(...);
                    break;
                case RecordType.Verbose:
                    WriteVerbose(...);
                    break;
                case RecordType.Debug:
                    WriteDebug(...);
                    break;
                case RecordType.Information:
                    WriteInformation(...);
                    break;
            }
        }

PowerShell の Cmdlet は本質的に同期的だが、 非同期処理を「Cmdlet スレッドに戻す」ことで非同期出力を実現できる。 BlockingCollection<T> を使ったこの方式は、PowerShell の制約を自然に回避する最も堅牢な方法のひとつだ。

Sashimi は外部コマンドの入出力をバイナリ(byte[])で行うことにフォーカスしたコマンド群だ。

動機

PowerShell の外部コマンド実行における問題点

PowerShell には内部にCmdletと呼ばれるコマンドや関数が用意されていて、基本的にはそれらを使用してコードを書くことになる。 他のシェルで言えばビルトイン・コマンドを多数抱えているようなものだ。 これらを使用している限り、PowerShellの特徴であるオブジェクト・ベースのパイプライン入出力が可能になる。

とはいえ、外部コマンドも必要になるし、実行も当然できるようになっている。 できるのだが、入出力に一定の制限が掛かる。 パイプライン入出力は 文字列 になる制限だ。

正確には全てが文字列になるわけではなく、外部コマンド1 | 外部コマンド2 と外部コマンドが連結されている場合、この間はバイナリで入出力が行われるのだがPowerShell上からは見えない内部に隠ぺいされた動きなので、全て文字列になると思って良い。

多くの場合はこれで問題ない。 だが、文字列では困る場合もある。

• バイナリデータそのものが欲しい
• 入出力で扱われる文字コードが、文字列化時のエンコーディングと合っていない

1番目の「バイナリデータそのものが欲しい」はまぁ稀だろうけど、2番目のは割と遭遇したことがあるのではないだろうか？

解決策

いちおう解決策はある。

外部コマンドを実行して、その出力が文字列化される時のエンコーディングをあらかじめ変更しておくことだ。 [Console]::OutputEncoding をコマンドが出力するエンコーディングに変えることで対応が可能となる。

try {
    $currentEncoding = [Console]::OutputEncoding
    [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
    $result = externalCommand # ←外部コマンド
} finally {
    [Console]::OutputEncoding = $currentEncoding
}

一応ね、これで解決はするんだけどさ、毎回こんな面倒なことやってられない。

というのが開発のきっかけ。

"Sashimi" について

プロジェクト名/モジュール名はあっさりと決まった。

• プロジェクト名には「食べ物」とか「料理」から引っ張ってくるのが個人的な流行
• 文字列ではなく、バイナリデータ（生データ）を扱う

⇒ 刺身！

インストール

PowerShell Gallery で公開している。

PowerShell 7.6 以上が必要な点に注意！

• PowerShell Gallery | Sashimi 3.0.0

Install-PSResource -Name Sashimi

コマンド紹介

Invoke-RawCommand (alias: raw)

主題のコマンド。

外部コマンドを実行し、標準入力/標準出力/標準エラー を byte[] で受け取るコマンド。

• ドキュメント: https://github.com/teramako/Sashimi/blob/main/docs/Sashimi/en-US/Invoke-RawCommand.md

PS1> Invoke-RawCommand echo abc
97
98
99
10
PS1> "うんこ" | Invoke-RawCommand cat
227
129
134
227
130
147
227
129
147

生データを扱うことが主題としてあるので、基本的には byte[] が出力されて上記のような結果になる。

さすがにこれでは非常に扱い難いｗ

ということで、-AsString パラメーター（alias: -s）と -Encoding パラメーター（alias: -e）がある。

PS1> Invoke-RawCommand -s echo abc
abc
PS1> "うんこ" | Invoke-RawCommand -s cat
うんこ

ちなみに、-AsString による文字列化だが、 行単位 で出力する仕様。

-Encoding はデフォルト(未指定)では UTF-8 になる。Shift_JIS出力されるものを扱いたい場合は -Encoding を指定する。

PS1> raw -s .\test-shift_jis.bat
�����Shift_JIS����
PS1> raw -s -e shift_jis .\test-shift_jis.bat
これはShift_JISだよ

標準エラー出力

-AsString は基本的に標準出力に作用するパラメーターだった。 対して、標準エラーは、-AsString の有無に関わらず文字列化する。

標準出力はバイナリになる可能性があるが、標準エラーは基本的にコンソールに印字されるべきものであり文字列だろう。という前提。

コマンド引数を正しく与える

以下を実行した時、どうなるか？

"abc`n" | raw -s cat -e

答え: エラーになる。

Invoke-RawCommand: Missing an argument for parameter 'Encoding'. Specify a parameter of type 'System.String' and try again.

-e が Invoke-RawCommand のパラメーターと解釈されてしまうためだ。

正しく cat コマンドに渡すには:

• "abc" | raw -s cat '-e' と引用符で囲って文字列であると明示する
• "abc" | raw -s cat -- -e と -- を付ける

少々面倒だが、我慢してもらうしかない。

ScriptBlockモード

上記のような課題と、raw ... | raw ... | raw ... と毎度 raw を付けるのが面倒。 ということで ScriptBlock モードを用意している。

raw -s { "abc`n" | cat -e | base64 }

{ ... } にPowerShellスクリプトを書くことができる。 (PowerShell 的に由緒正しいコードで、ScriptBlock という匿名関数に近いもの)

実はブロック内を AST 解析をして、外部コマンド部分と判断できた部分を書き換えて実行しており、 ただの1ステートメントに限らず複数のステートメントを書けるし、if や foreach 文を書くこともできる。変数も読み書きできる。

また、外部コマンドがパイプで連続している場合には、-AsString(-s)を末尾のみに適用させる工夫もしている。

よって、curl で画像(バイナリデータ)を取ってきて、img2sixel でSixelに変換し、文字列として出力するようなことができる。

$imgUrl = 'https://raw.githubusercontent.com/teramako/Sashimi/refs/heads/main/docs/img/Sashimi_512.png'
raw -s { curl $imgUrl | img2sixel -w256 }

ConvertTo-RawString (alias: b2a)

byte[] → string を行う補助コマンド。 ("binary to ascii" 略して "b2a")

• ドキュメント: https://github.com/teramako/Sashimi/blob/main/docs/Sashimi/en-US/ConvertTo-RawString.md

iconv -t utf8 -f ... と思ってくれて良い。

元々 Invoke-RawCommand に -AsString パラメーターがない時のもので、 raw ... | raw ... | b2a -e shift_jis みたいな使い方をして最終的に文字列を得ることを目的としていた。-AsString がある今は、このコマンドの存在意義は薄れた。

ただ、ConvertTo-RawString には -Raw パラメーターがある。 Invoke-RawCommand の -AsString と ConvertTo-RawString (-Rawなし)は行単位で出力し、改行コードは除去されるので、これでは不都合がある場合には使うことがあるだろう。

raw cat test.json | b2a -Raw | ConvertFrom-Json

ConvertFrom-RawString (alias: a2b)

string → byte[] を行う補助コマンド。 ("ascii to binary" 略して "a2b")

• ドキュメント: https://github.com/teramako/Sashimi/blob/main/docs/Sashimi/en-US/ConvertFrom-RawString.md

iconv -f utf8 -t ... と思ってくれて良い。

Invoke-RawCommand の標準入力に byte[] のみを受け付けていた時のもので、 "うんこ" | a2b | raw ... みたいな使い方を目的としていた。

Out-RawFile (alias: rawout)

byte[] → ファイル を行う補助コマンド。

• ドキュメント: https://github.com/teramako/Sashimi/blob/main/docs/Sashimi/en-US/Out-RawFile.md

PowerShellのリダイレクトや Out-File って、byte[] データをバイナリとして書き出してくれないので作った。

Show-HexDump (alias: hexd)

Unix系コマンドで言えば、hexdump コマンドにあたる。

• ドキュメント: https://github.com/teramako/Sashimi/blob/main/docs/Sashimi/en-US/Show-HexDump.md

元々はこれ単体で https://github.com/teramako/HexDump/ プロジェクトとして作っていたのだが、Sashimi と非常に相性が良いので取り込んだ。

マルチバイトの表示には結構こだわって作っていて絵文字のようなサロゲートペアとなるような文字も奇麗に出せる。

サンプル画像

旧HexDumpプロジェクト時に撮ったものなので若干古いけど、

カラーリングも行える

Test-RawCommand (alias: raw?)

• ドキュメント: https://github.com/teramako/Sashimi/blob/main/docs/Sashimi/en-US/Test-RawCommand.md

Invoke-RawCommand と内部でやっていることはほぼ同じだが、外部コマンドを実行したプロセスの終了コードによって真偽値（終了コードが 0 なら $true, それ以外は $false）を返すことを目的としている。

出力結果ではなく、終了コードによる条件分岐をしたい場面での使用を想定している。

標準出力、標準エラーは Information レコードとして出力をするので、後々結果を取り出すことも可能だ。

if (raw? grep pattern path/to/text -InformationVariable info) {
    $info.Where({$_.Tags -in "stdout"}).Message | Write-Output
} else {
    $info.Where({$_.Tags -in "stderr"}).Message | Write-Error
}

Powershell モジュールとして動くものができているので、ずいぶんを遅くなってしまったが、その報告。

• Sabamiso.psm (PowerShell Gallery | Sabamiso.psm)
• Sabamiso.completions (PowerShell Gallery | Sabamiso.completions)

以前は "NativeCommandCompleter.psm" というド直球な名前だったが改名した。 また、補完エンジンとなるコアのモジュールである Sabamiso.psm と、各コマンドの補完コードを集めた Sabamiso.completions に分離している。

Sabamiso.psm

補完エンジンと補完コードの登録を行うコマンド群を提供するモジュールである。

大枠の仕組みは PowerShell で外部コマンドの補完 に書いた時と変わっていない。

1. 補完開始
2. コマンドライン解析
3. コマンド指定がある
   • PowerShell コマンド(Cmdlet)の補完 (PowerShell本体の仕事)
   • コマンド名指定で補完コードが登録されている(Register-ArgumentCompleter -CommandName ... ) → その補完(登録されたスクリプト実行)
   • 上記2つに該当しない (← 本 Sabamiso.psm の仕事)
     • 実行コマンド名を取得、コマンド名の補完定義が登録済み(キャッシュ済み)か確認
     • 登録済み
       • 該当の補完定義から補完を開始
     • 未登録
       • 環境変数 PS_COMPLETE_PATH にある各ディレクトリ(環境変数 PS_COMPLETE_PATH は未設定なら、<$PROFILE のあるディレクトリ>/completions が設定される)から 実行コマンド名.ps1 のスクリプトを探す。
       • 見つかったスクリプトを実行。
       • 再度補完定義が登録されたか確認。(登録されていれば、「登録済み」へ)
   • 上記を通して補完候補がない
     • ファイル・ディレクトリ名補完 (PowerShell本体の仕事)

上記のような仕組みで動いている。

bash, zsh, fish 等のUnix系シェルの /usr/share/*/completions/, /etc/*/completions/ を真似していると言えば分かりやすいだろうか。

遅延読み込み

上記のような仕組みで補完発動時に動的に読むため、PowerShell起動時に各コマンド用の補完コードを読み込む必要がなくなり、起動時間が長くなる要因を削減できる。

また、後述するけれど posh-git のような既存の補完モジュールを再利用するかたちでの遅延読み込みも可能。

補完候補出力(menu-complete)には、その説明文が表示される

fish の補完で候補と共に説明が出てくるのが好きで、強くインスパイアしている。

Windows対応

Windows コマンドで / 始まりのパラメーターも補完できる。

また、上図のようにロケールに合わせてローカライズされた説明文も出せるようになっている。

特殊な形態のコマンド

少し工夫が必要だが、 dd コマンドのような - から始まらないような特殊なパラメーターにも対応できる。

Sabamiso.completions

私自身が使うために、かつ、サンプルとして定義している補完コード群。

補完コードのスクリプト

実際の補完コードがどんな風になるかを書いておこう。

私自身が使うために書いているコードも参考に: https://github.com/teramako/Sabamiso.completions/tree/main/completions

補完コードの役割は 「補完定義」を登録 することだ。 そのコマンドが Register-NativeCompleter になる。

一度登録されると、解除されない限りそのスクリプトは実行されないことに注意。

Register-NativeCompleter -Name "<コマンド名>" `
                         -Description "<コマンドの説明>" `
                         -Aliases @(別名) `
                         -Parameters @(パラメーター定義) `
                         -SubCommands @(サブコマンド定義) `
                         -Arguments @(コマンド引数定義) `
                         -Style 'スタイル' `
                         -NoFileCompletions

このコマンドで、定義と登録ができる。 定義のみを作る New-CommandCompleter もあるが、こちらは SubCommands のところで説明する。

• -Name: コマンド名。必須
• -Description: そのコマンドの説明。オプショナル
• -Aliases: 主にサブコマンド用。(tmux list-sessions = tmux ls のような別名を定義するもの)
• -Parameters: -i や --ignore-case 等のオプション定義群
• -SubCommands: git branch ... の branch 等のサブコマンド群
• -Arguments: コマンド引数の補完定義
• -NoFileCompletions: 引数の補完時、ファイルパスの補完を無効にする
• -Style: コマンドのスタイル (GNU(デフォルト), Unix, Windows)
  • GNU: GNU系コマンドのスタイル。
  • Unix: GNUとほぼ同じだが、--<ロングオプション>=<値> の =区切り指定はできない
  • Windows: オプション接頭辞が / になり、引数指定も /<オプション名>:<値> と : 区切りになる

Parameters

パラメーターの定義は New-ParamCompleter で行う。

New-ParamCompleter -ShortName @(ショートオプション名) `
                   -StandardName @(通常オプション名) `
                   -LongName @(ロングオプション名) `
                   -Description "説明" `
                   -Arguments <引数補完定義> `
                   -Style <スタイル>

• -ShortName: Unix系コマンドのショートオプション。
  • 一文字であること。
  • ls -lF の lF のように複数組わせられる。
  • 引数を必要する場合、 head -n10 のように、<ショートオプション><値> の入力が可能
  • 規定の接頭辞は -。
• -StandardName: 旧スタイルのUnix系コマンド(find コマンドとか)、または、Windowsによくあるオプション。
  • 規定の接頭辞は -。
• -LongName: いわゆるGNUロングオプション
  • 規定の接頭辞は --。
  • 引数を必要とする場合、 --file=..., --file ... と = または の区切りが可能
    • grep --color=<when> のような引数が無い場合にフラグとして作用するものの場合は、= のみが区切り
• -Arguments: 引数の定義
  • 省略すると、フラグのパラメーターとして作用する
  • 引数値をファイルパスなどの典型的な型、静的な候補リスト、動的にPowerShellスクリプトから補完する設定が可能
• -Style: パラメーター固有のスタイル
  • 基本的には親コマンド定義のStyleを引き継ぐが、特殊な事情がある場合に指定。通常は使わない。

例

grep コマンドから一部抜粋。

Register-NativeCompleter -Name grep -Parameters @(
    New-ParamCompleter -ShortName i -LongName ignore-case -Description 'Ignore case'
    New-ParamCompleter -ShortName f -LongName file -Description 'Use patterns from a file' `
                       -Arguments @{ Name = 'FILE'; Type = 'File' }
    New-ParamCompleter -LongName color `
                       -Arguments @{ Name = 'WHEN'; Nargs = '?'; Candidates = "auto","always","never" }
)

SubCommands

サブコマンドの定義は、通常のコマンド定義と同じ New-CommandCompleter で行う。

New-CommandCompleter -Name "<サブコマンド名>" `
                     -Description "<コマンドの説明>" `
                     -Aliases @(別名) `
                     -Parameters @(パラメーター定義) `
                     -SubCommands @(サブコマンド定義) `
                     -Arguments @(コマンド引数定義) `
                     -Style 'スタイル' `
                     -NoFileCompletions

パラメーターは Register-NativeCompleter と同じ。

例

Register-NativeCompleter -Name git -SubCommands @(
    New-CommandCompleter -Name log -Parameters @(
        New-ParamCompleter -ShortName g -LongName graph
        New-ParamCompleter -ShortName p -LongName patch
        New-ParamCompleter -ShortName n -LongName max-count -Arguments @{ Name = 'NUM' }
        New-ParamCompleter -LongName 'stat'
        New-ParamCompleter -LongName 'since','after' -Arguments @{ Name = 'date' }
        New-ParamCompleter -LongName 'until','before' -Arguments @{ Name = 'date' }
        New-ParamCompleter -LongName 'author','committer' -Arguments @{ Name = 'pattern' }
    )
    New-CommandCompleter -Name add -Parameters @(
        New-ParamCompleter -ShortName n -LongName dry-run
        New-ParamCompleter -ShortName v -LongName verbose
        New-ParamCompleter -ShortName f -LongName force
        New-ParamCompleter -ShortName p -LongName patch
        New-ParamCompleter -ShortName A -LongName all
    )
)

Arguments

引数の補完定義(Register-ArgumentCompleter や New-ParamCompleter の -Arguments パラメーターの記述方法)は、やり方が2通りある。

• New-ArgumentCompleter コマンドを使用する
• ただのハッシュテーブル(@{ ...})を使用する

どちらを使用しても良いが、コマンドを使用すると LanguageServer の支援を受けやすいが、冗長になりがちだ。 個人的な使い分けは、-Arguments に直接書く時はハッシュテーブルで簡潔に。使いまわすために変数に入れる時はコマンドとしている。

定義だが、補完候補を生成しないものと生成するものに3種類の合計4種類ある。

補完候補を生成しないもの

ただ引数が必要だと示すだけのもの。 特に引数が必須のオプションは -Arguments の指定を必須としているため、@{ Name = 'value名' } を各機会は多い。

New-ParamCompleter ... -Arguments (New-ArgumentCompleter -Name NUM)
# or
New-ParamCompleter ... -Arguments @{ Name = 'NUM' }

補完候補生成: ファイル/ディレクトリやコマンド補完

ファイル/ディレクトリのパスやコマンドを補完させるもの。-Type パラメーターを指定する。

New-ParamCompleter ... -Arguments (New-ArgumentCompleter -Name file -Type File)
New-ParamCompleter ... -Arguments (New-ArgumentCompleter -Name dir -Type Directory)
New-ParamCompleter ... -Arguments (New-ArgumentCompleter -Name cmd -Type Command)
# or
New-ParamCompleter ... -Arguments @{ Name = 'file'; Type = 'File' }
New-ParamCompleter ... -Arguments @{ Name = 'dir'; Type = 'Directory' }
New-ParamCompleter ... -Arguments @{ Name = 'cmd'; Type = 'Command' }

他にも DelegatingCommand という特殊なものがある。(sudo や time のように引数がコマンドで、それ以降はそのコマンドの補完が必要となるケース用)

補完候補生成: 静的なリスト

事前に候補が分かっている場合は、-Candidates パラメーターに列挙する。

New-ParamCompleter ... -Arguments (New-ArgumentCompleter -Name color -Candidates 'always','auto','never')
# or
New-ParamCompleter ... -Arguments @{ Name = 'color'; Candidates = 'always','auto','never' }

補完候補生成: 動的なスクリプト

PowerShell スクリプト(ScriptBlock) で補完候補を生成には -Script パラメーターを使用する。

New-ParamCompleter ... -Arguments (
    New-ArgumentCompleter -Name GROUP -Script {
        param([string] $wordToComplete)
        Get-Content '/etc/group' | ForEach-Object {
            if ($_ -match '^([^:]+):') {
                $group = $Matches[1]
                if ($group -like "$wordToComplete*") { $group }
            }
        }
    }
)
# or
New-ParamCompleter ... -Arguments @{
    Name = 'color';
    Script = {
        param([string] $wordToComplete)
        Get-Content '/etc/group' | ForEach-Object {
            if ($_ -match '^([^:]+):') {
                $group = $Matches[1]
                if ($group -like "$wordToComplete*") { $group }
            }
        }
    }
}

ローカライズ

https://github.com/teramako/Sabamiso.completions/tree/main/completions を見ると分かると思うが、-Description に指定する説明文を変数化している。

$msg = data { ConvertFrom-StringData @'
    key1 = text1
    key2 = text2
    # ...
'@ }
Import-LocalizedData -BindingVariable localizedMessages -ErrorAction SilentlyContinue;
foreach ($key in $localizedMessages.Keys) { $msg[$key] = $localizedMessages[$key] }

説明文のローカライズを可能とするためだ。

completions/ja 等のロケール・ディレクトリを作って コマンド名.psd1 を入れておくと読み込まれて、$msgディクショナリの各値が上書きされる。

参考: https://github.com/teramako/Sabamiso.completions/blob/main/completions/ja/whoami.psd1

既存のコマンド補完を再利用する

https://github.com/teramako/Sabamiso.psm/blob/main/README.md#example-3-use-posh-gits-completion に記載しているが、 補完用のモジュールが既にあってそれを再利用することも可能だ。 しかも、必要になった時に読み込まれる遅延読み込みのおまけつきで。

例えば、git コマンドの補完は posh-git があり、これを使用したい場合、以下のようなコードを <プロファイル・ディレクトリ>/completions/git.ps1 に記述することで実現できる。 プロファイル内で posh-git を無駄に読み込む必要もなくなる。

<#
.SYNOPSIS
    Regsiter `git` command completer with `posh-git`
.DESCRIPTION
    This script will be loaded by `Sabamiso.psm` poershell module.
.LINK
    dahlbyk/posh-git: A PowerShell environment for Git
    https://github.com/dahlbyk/posh-git
#>
param($wordToComplete, $commandAst, $cursorPosition)
Import-Module posh-git

# Reset the variable in the global scope
$global:GitPromptScriptBlock = $GitPromptScriptBlock

# The first time, generate the completion list manually
TabExpansion2 -inputScript $commandAst.ToString().PadRight($cursorPosition) `
              -cursorColumn $cursorPosition `
    | Select-Object -ExpandProperty CompletionMatches

Import-Module posh-git でモジュールを読み込む。すると、posh-git 側で Register-ArgumentCompleter -CommandName git ... の補完が登録される。 (次回以降は)Register-ArgumentCompleter -CommandName git ...で登録された補完スクリプトが呼ばれることになる。 初回は TabExpansion2 関数を手動で呼んで補完させる。

コマンド自身が補完候補を返すような、たとえば dotnet complete のようなものの場合、<プロファイル・ディレクトリ>/completions/dotnet.ps1 に以下のようなコードを書く。

<#
.SYNOPSIS
    Regsiter `dotnet` command completer
.DESCRIPTION
    This script will be loaded by `Sabamiso.psm` poershell module.
.LINK
    How to enable tab completion for the .NET CLI
    https://learn.microsoft.com/en-us/dotnet/core/tools/enable-tab-autocomplete
#>
param($wordToComplete, $commandAst, $cursorPosition)

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock {
    param($wordToComplete, $commandAst, $cursorPosition)
    dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
    }
}
# The first time, generate the completion list manually
TabExpansion2 -inputScript $commandAst.ToString().PadRight($cursorPosition) `
              -cursorColumn $cursorPosition `
    | Select-Object -ExpandProperty CompletionMatches

$PSDefaultParameterValues["Out-Default:OutVariable"] = "LAST"

上記コードを $PROFILE に仕込んでおくと、コマンド実行結果が $LAST 変数に入る。

PS1> Get-ChildItem

    Directory: ....

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2022/05/24    17:12                *********
...

PS1> $LAST

    Directory: ....

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2022/05/24    17:12                *********
...

PS1>

直前のコマンド実行結果を再度確認したい時や、加工したい場合に便利。

仕組み

Out-Default コマンドレット

• Out-Default

PowerShell はコマンドラインをAST解析して、各コマンドをまとめたパイプラインにまとめる。 このパイプラインの最後のコマンドがFormat系(Format-ListやFormat-Table)でない場合に、暗黙的にOut-Defaultを末尾に追加する動きをしている。

• Get-ChildItem → Get-ChildItem | Out-Default
• Get-ChildItem | Select-Object ... → Get-ChildItem | Select-Object ... | Out-Default
• Get-ChildItem | Format-List ... → Get-ChildItem | Format-List ... (末尾がFormat-* なのでOut-Default は追加されない)

-OutVariable パラメーター

• about_CommonpPrameters

また、すべてのコマンドレットには、出力結果を引数に指定した変数名の変数に収める -OutVariable というパラメーターを指定できる。 パイプラインに出力するオブジェクトを出力と同時に変数に収める。

変数は ArrayList 型で、出力が単一であっても配列になる点に注意。

$PSDefaultParameterValues 変数

• about_Parameters_Default_Values

$PSDefaultParameterValues のディクショナリのキーに <コマンド名>:<パラメーター名>、値にそのパラメーターの値を入れるとパラメーターの規定値を設定できる。

これらを組み合わせる。

$PSDefaultParameterValues["Out-Default:OutVariable"] = "LAST"

すると、Get-ChildItem ... は Get-ChildItem | Out-Default -OutVariable LAST に変換される。

使い道

フィルタリングする

PS1> Get-ChildItem
...
PS1> $LAST | Where-Object Length -gt 1MB

直前の結果をログに残す

PS1> Get-ChildItem
...
PS1> $LAST | ConvertTo-Json | Set-Content file-list.json

Unix系のコマンドが使えるようになる core-utils がMicrosoftからリリースされている。 (参考: ニュースにもなった)

• リポジトリ: https://github.com/microsoft/coreutils

普通にインストールすると、C:\Program Files\coreutils にインストールされる。 C:\Program Files\coreutils\bin に各exeファイルが入っている。 各exeファイルすべてが 8MB 近くあるように見えるが、ハードリンクで構成されているため実態は小さい。

ちょっと面白いのは coreutils-manager.exe があって、このコマンドで使うコマンドの管理(ハードリンクの作成(enable)/削除(disable))ができる。

> coreutils-manager disable ls

とすると ls.exe が消える。有効にするなら coreutils-manager enable ls とすれば良い。 coreutils-manager status で状態一覧も見られる。

まぁこれ自体は良い。 Microsoft自身がネイティブで動くコマンドを用意してくれて喜ばしいことだ。

お行儀が悪い

ただ、かなりお行儀が悪いことをしてくれる。

バージョン 2026.6.16 時点での話だが、インストールすると勝手にPowerShellプロファイルにコードを仕込むのだ。以下のコードが追加される。 https://github.com/microsoft/coreutils/blob/a350b9cf5c9c178b1089902cde89275688862e32/src/pwsh-install-template.ps1

コマンドライン実行時に呼ばれる関数 PSConsoleHostReadLine を上書きして、coreutilsで有効になっているコマンド名のものがあったら、coreutilsのフルパスに変換してしまうようなことをしている。

PowerShell の動きとしてはコマンド部分をエイリアス、関数、コマンドレットから検索し、見つからなかったら PATH環境変数から外部コマンドを検索するが、フルパスに置き換えられるため、これらの検索は行われずにダイレクトに core-utils のコマンドが実行されることになる。 ls や cat など、PowerShell 自体がエイリアスとして Get-ChildItem や Get-Content になっていてもガン無視される。

問題点

• 何の注意喚起もない
• 訓練されたPowerShellユーザーは ls は Get-ChildItem のエイリアスになっていて、外部コマンドよりも優先度が高いことを知っている。 Get-ChildItem のつもりで ls を実行して混乱することになる。
• ls のパラメーターをタブ補完しようとすると、PowerShell本体は ls を Get-ChildItem と認識しているので core-utilsの ls.exe ではなく Get-ChildItem のパラメーターを補完するになり不整合が生じる

インストール時と言ったが、それは嘘だ

正確には、冒頭で挙げた coreutils-manager.exe でコマンドの有効化/無効化を行ってもプロファイルの仕込みが走る。

無効化する術が分からない

インストール/アップデート時のみ気を付けておけば良いとは限らないことが分かったので、本格的に無効化する（書き換えが走っても実質スキップされるような）術を探った。

が、結論としては分からなかったorz

プロファイルには以下のようなヘッダー、フッターが付いている。 ここだけ残せば書き換えがコードの仕込みを抑制できるのでは？ → ダメだった。

# DO NOT MODIFY -- coreutils -- 60b36fc6-2d59-49df-be51-28dd2f4c3c9a
# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
...
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# DO NOT MODIFY -- coreutils -- 60b36fc6-2d59-49df-be51-28dd2f4c3c9a

途中の function PSConsoleHostReadLine { ... } を実質何もしないコードにしておく案は？ → ダメだった。

function PSConsoleHostReadLine {
    param()
    return [Microsoft.PowerShell.PSConsoleReadLine]::ReadLine($host.Runspace, $ExecutionContext, $?)
}

Issue になっている

• https://github.com/microsoft/coreutils/issues/161

まぁ当然のようにIssueに登録されている。

修正されるのを待つしかない。

PowerShell で外部コマンドの補完をするモジュールを開発中だよ

• teramako/NativeCommandCompleter.psm

なんだかんだ不満がありつつも、Linux(WSL)上で PowerShell を触っている今日この頃。

ただの文字列ではなくオブジェクトとして扱えることや、.NET の資産を使えることが大きい。 ただ、PowerShell 内のみの Cmdlet だけでは窮屈で外部コマンドを使用したいことが多々ある。というか外部コマンドでないとできないことが多い。 そうなるとPowerShellは無力だ。

出力はただの文字列だし、エラーハンドリングは面倒だし、コマンドラインの補完が全く効かないし。

そう、コマンドライン補完だ。

Linux の bash, zsh, fish 等々のシェルは外部コマンドの補完ができる。 この補完のおかげでコマンドライン生活ができるのだ。

PowerShell だってその点は分かっている。 Register-ArgumentCompleter を用いて外部コマンドの補完スクリプトの登録が可能だ。

でも、これ、$PROFILE 等に一つ一つ丁寧に各コマンドの補完スクリプトを登録する必要がある。

Linux上で外部コマンドが幾つあると思っているんだ。

PowerShell 7.6.0-preview.5

そんな不満を持っていたところ、PowerShell 7.6.0-preview.5 がリリースされた。

Add the parameter Register-ArgumentCompleter -NativeFallback to support registering a cover-all completer for native commands (#25230)

なにやら面白そうなのが追加されているじゃないですか。

Register-ArgumentCompleter -NativeFallback

簡単に言うと、全コマンドで補完時に Register-ArgumentCompleter に与えたコードを通すことができるようになった。

これまでは、 Register-ArgumentCompleter -CommandName <string[]> -ScriptBlock <scriptblock> [-Native] [<CommonParameters>] で、外部コマンドの補完コードを定義していたが、-CommandName コマンド名の指定が必要だった。

これが、Register-ArgumentCompleter -ScriptBlock <scriptblock> [-NativeFallback] [<CommonParameters>] と、コマンド指定不要でコード登録ができるようになった。

1. 補完開始
2. コマンドライン解析
3. コマンド指定がある
   • PowerShell コマンド(Cmdlet) → Cmdletの補完(PowerShell内部コード)
   • コマンド名指定で補完コードが登録されている → その補完(登録されたスクリプト実行)
   • NEW: 上記2つに該当しない → 登録されたスクリプト実行(フォールバック的に)
   • 上記を通して補完候補がない → ファイル・ディレクトリ名補完

といった感じ。

補完コードの動的読み込み

Linux のシェル ―― bash, zsh, fish 等では、 /etc/bash_completion.d 等に各コマンドの補完コードが入っていて、必要に応じて読み込まれる。

これらと同じ事ができるよね？

早速試したが、…できた。

モジュール開発

ということで、開発中である。

• teramako/NativeCommandCompleter.psm

fish の補完が気に入っているので、強くインスパイアされた補完リスト出力になっている。

組み込みで補完可能なコマンドの定義は以下にある

• https://github.com/teramako/NativeCommandCompleter.psm/tree/main/completions

メインはLinuxコマンドの補完だが、Windowsのコマンドも補完できるようにクロスプラットフォームに気を使っている（つもり）。 おかげでWindows用やLinux用(一部macOS/BSD用もあり)がごちゃまぜ状態…。

モジュールと補完定義は別リポジトリにすべきだったと少し後悔している。 C# プロジェクトだったのに、ご覧のありさまだ。

PowerShell モジュールを開発していてヘルプを英語で出したり日本語に切り替えたりしたくなった。

ヘルプの言語環境は UICulture が関わってくる。この値を設定し直せれば切り替え可能。

結論

• [System.Threading.Thread]::CurrentThread.CurrentUICulture を設定せよ。

LANG 環境変数

LANG=ja_JP.UTF-8 pwsh

LANG=環境変数は有効に働くみたい。 ただし、pwsh プロセスの再起動が必要。

$PSUICulture

PowerShell の自動変数に、$PSCulture と $PSUICulture がある。 しかし、この変数は読取専用であり、ここに新たな値を設定することができない。

PS> $PSCulture = "ja-JP"
WriteError: Cannot overwrite variable PSCulture because it is read-only or constant.

[cultureinfo]::CurrentUICulture

こちらは設定可能で、有効に働いた。

[cultureinfo]::CurrentUICulture = "ja-JP"

Import-Module MyModule -Force
Get-Help Test-Cmd

既に読み込んでいるモジュールは再読み込みさせないと切り替わらない。

あと、$PSUICulture に反映されない点がなんだか気持ち悪い。

[System.Threading.Thread]::CurrentThread.CurrentUICulture

現行スレッドのオブジェクトにも UICulture を設定できるようだったのでやってみたら、当りだった。

PS> [System.Threading.Thread]::CurrentThread.CurrentUICulture = "ja-JP"
PS> $PSUICulture
ja-JP

PS> Import-Module MyModule -Force
PS> Get-Help Test-Cmd

TLS(SSL) 証明書を作成する Makefile を作った。

• CA, サーバー証明書、クライアント証明書の生成が可能
• ECDSA な秘密鍵生成にも対応
• PKCS12 フォーマットへ出力が可能
• x509 v3 拡張を使用
  • サーバー証明書には SAN 値の設定が可能