PowerShell Scripting Weblog

PowerShellらしい関数の書き方 [PS Advent Calendar '12]

今日から、PowerShell Advent Calendar 2012が始まりました。初日は私が担当させていただきます。お題は旬の話題、PowerShell 3.0の新機能！…ではなく、初心に返って、PowerShellの「関数」ってどう書くのがいいのかというお話をします。PowerShell 3.0どころか、大部分はPowerShell 1.0から変わっていない基本の話です。

これは今までずっと書きたかったネタですがなかなか書く暇がなくて放置してたものです。3.0の話はきっと他の皆さんが書いて下さるはず！私もまた順番が回ってきたら書こうと思います。

PowerShellの関数は従来言語とだいぶ違う

PowerShellを使いこなすようになってくると、他の言語を使う時と同じで、定型処理は関数として一つにまとめたくなってきます。ところが他の言語と同じような感覚で関数を書くと、どうもうまくいかないのです。

たとえば引数にフォルダパスとフォルダ名を指定すると、指定フォルダが存在すればFalseを返し、存在しなければ作成してTrueを返す関数を書いてみました。

function MakeDir($path,$name)
{
    $newDirPath = Join-Path $path $name
    if((Test-Path $newDirPath))
    {
        return $false
    }
    else
    {
        New-Item -ItemType Directory -Path $newDirPath 
        return $true
    }
}

実行は

MakeDir("C:\test","NewFolder")

と、メソッド風に呼び出すことはできないので、コマンドレット風に

MakeDir C:\test NewFolder

と呼び出せばいいんですが（まあ最初はここもつまづきポイントではありますが）、この実行結果は以下のようになります。

    ディレクトリ: C:\test

Mode                LastWriteTime     Length Name 
----                -------------     ------ ----
d----        2012/12/01      7:51            NewFolder
True

フォルダが作成されてTrueが返却されることを想定していたのに、なんか余計な出力が混じってしまっています。なんでしょうこれは？

実はPowerShell関数内で値が出力されると、returnキーワードがついてなくてもすべて呼び出し元に出力されるという仕様なのです。そしてPowerShellにおけるreturnキーワードの効果は「後続処理を打ち切って呼び出し元に戻る。ただしreturnの後に値が指定してあればそれを最後の値として戻す」となります。そのため、呼び出し元に返したくない出力が関数内にある場合は、すべて[void]にキャストしたり|Out-Nullとしてリダイレクトするなどして出力を破棄する必要があるのです。このMakeDir関数の場合はNew-Itemコマンドレットが作成したフォルダのFolderInfoオブジェクトを出力するので、これをNew-Item -ItemType Directory -Path $newDirPath | Out-Null のように破棄してやる必要があるわけです。

パイプラインの動作

先ほどの例を見ると、「いやいやなんでそんな訳のわからない仕様なんだよ、returnあるときだけ値返せよ」とお思いかと思います。しかしこれはPowerShellの特長の一つである、コマンドのパイプラインによる連携を行うための仕様なんです。

ここでコマンドを繋ぐパイプラインがどういう動作をしてるか、おさらいします。

Get-Process | where {$_.Handles -ge 500} | foreach {$_.Path}

これはハンドル数が500以上のプロセスのメインモジュールファイルのパスを取得するというコマンドで、別に何の変哲もありません。ところが、このコマンドがやっている処理を、次のように誤解してませんでしょうか？

�@ 稼働中のすべてのプロセスの一覧を配列として取得する。
�A �@で取得した配列を走査して、Handlesプロパティの値を調べる。Handlesが500以上のオブジェクトだけ抽出した配列を生成する。
�B �Aで生成した配列を列挙して、{}内のスクリプトをそれぞれ実行する。

しかし、これは間違いです。

正しくは

�@ 稼働中の1つのプロセスオブジェクトを取得して次のコマンドへ送る。
�A そのプロセスのハンドル数が500以上なら、次のコマンドへ送る。そうでないなら�@に戻る。
�B そのプロセスに対して{}内のスクリプトを実行する。まだ未取得のプロセスが残っていれば�@に戻る。

という動きをしています。つまり、パイプラインの手前で一旦すべての処理を終えてから、出力オブジェクトがまとめて配列という形で次のコマンドに送られるのではなく、オブジェクトがパイプラインの先頭から末尾に向けて1つずつ通過していき、それが先頭コマンドの出力オブジェクト数だけ繰り返される、という動作をしているのです。

これがPowerShellのパイプライン処理が、従来の処理系での関数と決定的に違うところで、パイプラインによって複数のコマンドが、あたかももとからあった単一のコマンドのように密に連携するわけです。

（この処理、.NETのLINQにちょっと似てると思う方もいらっしゃると思います。しかしLINQとは全然違うものです。なんせPowerShellはLINQより先に世に出てますし！ しかし類似点も多いのでいずれ比較なんかを書きたいと思ってます）

パイプラインで連携可能な関数の書き方

さて、先ほどのパイプラインの話ではコマンドレットを連携させていました。しかしPowerShellにおいてはコマンドレットも関数も、それが.NETのクラスかPowerShellのスクリプトなのかの違いがあるだけで、基本は同じ「コマンド」です。なので、関数もコマンドレットと同様、適切な記述をおこなえば、パイプラインでコマンド同士を連携させることが可能です。

以下に、Get-Repeatという関数の例を挙げます。この関数は-Textパラメータに文字列を指定し、-Countパラメータに回数を指定すると、指定文字列を指定回数分連結した文字列を出力する、という何の変哲もない関数です。しかしパイプラインからの入力を受け付け、次のパイプラインへ出力することを想定した作りになっています。

function Get-Repeat
{
    param(
        [Parameter(ValueFromPipeline=$true,Mandatory=$true)]
        [string[]]
        $Text,
        
        [int]
        $Count=2
    )

    begin
    {
    }

    process
    {
        foreach($s in $Text)
        {
            $s * $count
        }
    }

    end
    {
    }
}

以下は実行例です。

PS> Get-Repeat -Text ab -Count 2
abab
PS> "ab" | Get-Repeat -Count 2
abab
PS> Get-Repeat -Text ab,cd -Count 2
abab
cdcd
PS> "ab","cd" | Get-Repeat -Count 2
abab
cdcd

このように、パラメータに値を指定してもパイプラインから入力しても、スカラー値（配列ではない単一のオブジェクト）でも配列でも、正しく処理されています。

この関数をポイントごとに見ていきましょう。

PowerShellの正式な関数はparam節、beginブロック、processブロック、endブロックに分かれます。param節にはパラメータを指定します。beginブロックにはパイプラインで連携した際、最初の1回だけ実行される初期化処理、endブロックには最後の1回だけ実行される後始末処理を記述します。beginとendは今回の例では内容を省略しています。processブロックには、パイプラインから入力された1つのオブジェクトに対してその都度実行される処理を記述します。

ちなみに、

コマンド�@|コマンド�A|コマンド�B

とある場合、各コマンドにおけるbegin,process,endブロックは次のような順番で呼び出されます。

コマンド�@begin→コマンド�Abegin→コマンド�Bbegin→{コマンド�@process→コマンド�Aprocess→コマンド�Bprocess→コマンド�@process…}→コマンド�@end→コマンド�Aend→コマンド�Bend

processブロックでの処理は、通常はパイプラインだけではなくパラメータからも値を入力できるようにしておきます。そのためにはparam節に記述するパラメータに「このパラメータはパイプラインから値を入力することもできる」を意味する[Parameter(ValueFromPipeline=$true)]という属性を指定します（この属性はPowerShell 2.0から利用可）。今回のパラメータには「このパラメータは必須である」を意味するMandatory=$trueもあわせて指定しています。

先述の通り、パイプラインから入力される場合は配列ではなくオブジェクトが単体で渡されるのですが、パラメータから入力される場合はスカラー値と配列値、どちらの可能性もあるため、[string[]] のようにパラメータの型を配列型にしておくことで、どちらを指定しても処理できるようにしています。

processブロックではパラメータ経由で配列値が渡された場合に、各要素に対して処理を行うためforeachループを設けています。ちなみにスカラー値が渡された場合もforeachは問題なく処理します。

processブロック内では、returnは記述しません。returnするとその時点で関数が終了してしまうので正しくすべての出力ができなくなってしまいます。

特にこの例の関数のように入力型と出力型が同一の場合は、processブロックでは1オブジェクトの入力に対して、1オブジェクトを出力するようにしておくと、他のコマンドと連携させやすくなります。ただしWhere-Objectコマンドレットのようにフィルタ処理を行う関数の場合は、条件によっては何も出力しないようにします(空の配列とか$nullを返すのではないことに注意)。もちろん入力オブジェクトから何らかの配列値を出力する場合もありえます。

最低限、これらのポイントを押さえて関数を記述すると、他のコマンドとパイプラインで連携しやすい、PowerShellらしい関数を書くことができると思います。

まとめ

PowerShellでは従来言語と同じ感覚で関数を書くと、うまくいかないことが多いです。もっとも単に処理をひとまとめにしたいというニーズだけならばそれでも問題ないのですが、関数同士を組み合わせたいときに問題が顕在化します。

パイプラインの真の動作を理解し、パイプラインの中に組み込んで動作させることを想定した関数を記述すると、他のコマンドレットあるいは自作関数と連携しやすくなり、PowerShellの真の力を解放することができると思います。

PowerShell Advent Calendar 2012の1日目にしてはえらい固いネタかもですが、基本をおさらいするのも大事ですよね。

さて、明日は@jsakamotoさんの番です。よろしくお願いします。

「シェル操作課題」をPowerShellでやってみた

シェル操作課題 (cut, sort, uniq などで集計を行う) 設問編 - Yamashiro0217の日記

ログファイルをコマンド使って解析するというこの課題。

え。Windows？まさか？？？cygwin入れたり、vmでやってみたり、開発サーバーで作業すればいいんじゃないっすか（ホジホジ）

いやいやWindowsでシェルと言えばPowerShellでしょう！というわけでやってみました。出力形式に関しては本筋とは関係ないと思うので、PowerShellのデフォルトのままです。

準備

$logs = Import-Csv hoge.log -Header ServerName,UnixTime,UserId,AccessUrl

問1 このファイルを表示しろ

$logs

問2 このファイルからサーバー名とアクセス先だけ表示しろ

$logs|select ServerName,AccessUrl

問3 このファイルからserver4の行だけ表示しろ

$logs|where {$_.ServerName -eq "server4"}

問4 このファイルの行数を表示しろ

$logs|measure

問5 このファイルをサーバー名、ユーザーIDの昇順で5行だけ表示しろ

$logs|sort ServerName,{[int]$_.UserId}|select -First 5

問6 このファイルには重複行がある。重複行はまとめて数え行数を表示しろ

$logs|sort * -Unique|measure

問7 このログのUU(ユニークユーザー)数を表示しろ

$logs|sort UserId -Unique|measure

問8 このログのアクセス先ごとにアクセス数を数え上位1つを表示しろ

$logs|group AccessUrl -NoElement|sort Count -Descending|select -First 1

問9 このログのserverという文字列をxxxという文字列に変え、サーバー毎のアクセス数を表示しろ

$logs|group {$_.ServerName -replace "server","xxx"} -NoElement|sort Count -Descending

問10 このログのユーザーIDが10以上の人のユニークなユーザーIDをユーザーIDでソートして表示しろ

$logs|where {[int]$_.UserId -ge 10}|select -Expand UserId|sort -Unique

PowerShellはテキスト情報をテキストのまま扱うのではなく、オブジェクトとして扱うところが特徴で、CSVファイルもImport-Csvコマンドレットを用いることで、ヘッダ文字列をプロパティ名として各行をオブジェクトとして読み込んでくれます。

あとは各種オブジェクト処理のコマンドレットに、パイプライン経由でオブジェクトを渡していくだけです。コマンドが何をやっているのかも、列番号ではなくプロパティ名を指定してやるので分かりやすいと思います。この課題に寄せられた回答の中では、シェル操作課題 SQLによる解答例が近いかと思います。

今回はCSVから情報を読み込んでいますが、ソースは別になんであってもいいわけです。たとえばGet-EventLogコマンドレットだとイベントログから持ってくることもできますし、XMLなら$xml=[xml](Get-Content file.xml)みたいな感じです。一旦オブジェクトとして取得できてしまえば、あとの処理方法は基本的に同じなので悩む必要がないのが良いところです。

そしてPowerShellの良いところはやはり、外部処理コマンドを使わずとも、シェル言語と組み込みコマンド（コマンドレット）のみで処理が完結するところです。たとえばbashだけでやるとtsekine's miscellaneous thoughts: シェル操作課題への回答のような大変なことになるようです。sortなど基本的なコマンドは使用するにしても、複雑なフィルタ処理などはawkを組みあわせる等しないと、特に後半の処理は辛いでしょう。PowerShellなら異なる処理系を持ち出す必要がなく、PowerShellのみですべて行えます。

もちろん問題点も色々あります。まず第一に、今回の課題のように、ヘッダ文字列がないCSVの場合は例のようにヘッダー文字列（＝プロパティ名）を自分で定義してやる必要が出てきます。そのため可読性はともかく、若干、冗長なところがでてきてます。まあ例のように一旦オブジェクトを作って変数に入れてしまえばあとは使いまわせますが、そこはちょっと厳しい点かもしれません。

あとImport-CsvコマンドレットはCSVの各エントリをすべて文字列型のプロパティとしてオブジェクトに格納するところがちょっと微妙な気がしました。数値は数値型で入れてほしいですよね。おかげで何か所か、[int]にキャストせざるを得ない部分が出てきました。

そして処理速度の問題。おそらくログファイルが巨大だとかなりリソースを食って時間もかかると思います。処理を分ける、バックグラウンドジョブやワークフローで動かす、そもそもログファイルを分割保存するようにしておく、等、実運用上では工夫が必要かと思います。

（5:14追記）
既出でした＞＜　[Power Shell] シェル操作課題への回答 - Pastebin.com（by @usamin5885さん）