Mercurial は、情報表示の体裁を制御する強力な仕組みを提供しています。この仕組みはテンプレートに基づいており、テンプレートを使用することで、単発のコマンド出力の固有化も、 Mercurial 組み込みのウェブインタフェースの見かけ全体のカスタマイズもできます。
Mercurial には即使用できる出力「様式」の幾つかが同梱されています。「様式」とは、誰かによって書かれて、 Mercurial が探し出せる何処かにインストールされた、事前に用意されたテンプレートのことです。
Mercurial に同梱された「様式」を見る前に、 Mercurial の標準的な出力を見てみましょう。
この出力は有益ではありますが、チェンジセット毎に5行という多くの表示領域が必要ですcompact 様式は、表題等を省くことで、この出力を3行に低減します。
changelog 様式からは、 Mercurial のテンプレートエンジンの持つ表現力を垣間見ることができます。この様式は、 GNU プロジェクトの changelog ガイドライン[RS]に沿った出力を行います。
Mercurial の既定出力様式がdefault という名前であることを知っても驚くほどのことは無いでしょう。
好みの様式の名前をhgrc ファイルで指定することで、 Mercurial がコマンド実行の際に使用する出力様式を変える事ができま す。
自分自身で様式を定義した場合、自分の様式ファイルへのパスを指定する方法と、自分の様式ファイルを Mercurial が探し出せる場 所へコピーする方法(一般には Mercurial がインストールされたディレクトリ直下のtemplates ディレクトリ)のどちらででも、自分 の様式ファイルを使うことができます。
“log的な” 全ての Mercurial コマンドに対して、様式やテンプレートを適用できます。例えば、“hg incoming”、“hg log”、“hg outgoing” および “hg tip” がそうです1 。
筆者がこのマニュアルを執筆している時点では、様式やテンプレートに対応しているコマンドは、それ程多くありません。 しかし、対応済みのコマンドは、出力のカスタマイズが必要性が非常に高いコマンド群でしたので、 Mercurial ユー ザのコミュニティからは、他のコマンドにおける様式やテンプレートへの対応の要望は、今のところあまりありませ ん。
Mercurial で言うテンプレートとは、大雑把に言うなら一片のテキストです。決して変更されない部分がある一方で、必要に応じて展 開や新たなテキストでの置換が実施されます。
詳細を説明する前に、 Mercurial の通常出力の簡単な例をもう一度見てみましょう。
それでは、出力を変えるためのテンプレートを指定して、同じコマンドを実行してみましょう。
上記の例は、可能な限り最も簡単なテンプレートとして、チェンジセット毎に表示される静的なテキストを指定するだけの例で す。“hg log” コマンドに対する--template オプション指定は、チェンジセット毎の表示の際に使用するテンプレートとして、指定さ れたテキストを使用することを Mercurial に指示します。
上記のテンプレート文字列は、 “\n” で終了している点に注意してください。これはエスケープシーケンスと呼ばれるも ので、個々のテンプレート要素の終端で改行を表示することを Mercurial に指示します。この改行を省略した場合、 Mercurial は個々の出力要素を単一行で出力します。エスケープシーケンスに関する詳細は、11.5 節を参照してくださ い。
常に固定された文字列を表示するテンプレートは、あまり有用とは言えませんので、もう少し複雑なものに挑戦してみましょ う。
ご覧の通り、テンプレート中の “{desc}” 文字列は、チェンジセット毎のログメッセージで置換されて出力されます。波括弧(“{” 及び “}”)で囲まれたテキストが検出された際には、どんなテキストが囲まれていた場合でも常に、括弧およびテキスト部分の展開が Mercurial により試みられます。波括弧そのものを表示したい場合は、11.5 節で述べる方法で、波括弧をエスケープしなければなりま せん。
以下のキーワードを使用することで、すぐにでも簡単なテンプレートを書くことができます。
幾つか実験してみることで、これらのキーワードを使用した際に期待される動作を見ることができます。図 11.1を参照してくださ い。
前述したように、date キーワードは可読性のある出力を生成しませんので、特別扱いする必要があります。そのためには filter を使う必要がありますが、詳細は 11.6 節を参照してください。
Mercurial のテンプレートエンジンは、最も広く使われている文字列エスケープシーケンスを認識します。バックスラッ シュ(“\”)を検知した際には、それに続く文字を見て、それら2つの文字を以下に示すような単独の文字に置換しま す。
上記のように、 “\”、 “{” ないし “{” そのものを含むテンプレートを使用したい場合、これらはエスケープされなければなりませ ん。
テンプレート展開における結果のうちの幾つかは、直ちに使えるほど簡便なものではありません。 Mercurial は、キーワードの展開結 果を変更するために、任意のフィルタの連鎖を指定することを求めてきます。上記の実行例において既に、一般的なフィルタである isodate を、日付を読めるようにするために使用しています。
Mercurial がサポートする最も一般的に使用されるフィルタのリストを、以下に示します。任意のテキストに適用できるフィルタも あれば、特定の状況下でのみ適用可能なものもあります。個々のフィルタの説明は、名前に続いて利用可能な状況を提示し、それに効果 の説明が続く形式となっています。
1 $ hg log -r1 --template ’{author}∖n’
2 Bryan O’Sullivan <bos@serpentine.com> 3 $ hg log -r1 --template ’{author|domain}∖n’ 4 serpentine.com 5 $ hg log -r1 --template ’{author|email}∖n’ 6 bos@serpentine.com 7 $ hg log -r1 --template ’{author|obfuscate}∖n’ | cut -c-76 8 Bryan O'Sulli 9 $ hg log -r1 --template ’{author|person}∖n’ 10 Bryan O’Sullivan 11 $ hg log -r1 --template ’{author|user}∖n’ 12 bos 13 $ hg log -r1 --template ’looks almost right, but actually garbage: {date}∖n’ 14 looks almost right, but actually garbage: 1248126514.00 15 $ hg log -r1 --template ’{date|age}∖n’ 16 3 seconds 17 $ hg log -r1 --template ’{date|date}∖n’ 18 Mon Jul 20 21:48:34 2009 +0000 19 $ hg log -r1 --template ’{date|hgdate}∖n’ 20 1248126514 0 21 $ hg log -r1 --template ’{date|isodate}∖n’ 22 2009-07-20 21:48 +0000 23 $ hg log -r1 --template ’{date|rfc822date}∖n’ 24 Mon, 20 Jul 2009 21:48:34 +0000 25 $ hg log -r1 --template ’{date|shortdate}∖n’ 26 2009-07-20 27 $ hg log -r1 --template ’{desc}∖n’ | cut -c-76 28 added line to end of <<hello>> file. 29 30 in addition, added a file with the helpful name (at least i hope that some m 31 $ hg log -r1 --template ’{desc|addbreaks}∖n’ | cut -c-76 32 added line to end of <<hello>> file.<br/> 33 <br/> 34 in addition, added a file with the helpful name (at least i hope that some m 35 $ hg log -r1 --template ’{desc|escape}∖n’ | cut -c-76 36 added line to end of <<hello>> file. 37 38 in addition, added a file with the helpful name (at least i hope that some m 39 $ hg log -r1 --template ’{desc|fill68}∖n’ 40 added line to end of <<hello>> file. 41 42 in addition, added a file with the helpful name (at least i hope 43 that some might consider it so) of goodbye. 44 $ hg log -r1 --template ’{desc|fill76}∖n’ 45 added line to end of <<hello>> file. 46 47 in addition, added a file with the helpful name (at least i hope that some 48 might consider it so) of goodbye. 49 $ hg log -r1 --template ’{desc|firstline}∖n’ 50 added line to end of <<hello>> file. 51 $ hg log -r1 --template ’{desc|strip}∖n’ | cut -c-76 52 added line to end of <<hello>> file. 53 54 in addition, added a file with the helpful name (at least i hope that some m 55 $ hg log -r1 --template ’{desc|tabindent}∖n’ | expand | cut -c-76 56 added line to end of <<hello>> file. 57 58 in addition, added a file with the helpful name (at least i hope tha 59 $ hg log -r1 --template ’{node}∖n’ 60 1f5a344665d8e800e1d88631d873fada9816c8f5 61 $ hg log -r1 --template ’{node|short}∖n’ 62 1f5a344665d8
|
所定の形式での出力を得るために、簡単にフィルタを組み合わせることができます。以下の例では、ログメッセージの冒頭・末尾の空白 を除外し、 68 桁に収まるように改行した後で、さらに8文字分(タブ文字が慣習的に8文字として扱われる Unix 的な環境では)の字 下げが、フィルタ連鎖により実施されます。
テンプレートにおける “\t” (タブ文字)の利用は、最初の行の強制的な字下げを行うためのものであることに注意してくださ い。tabindent が最初の行以外の全ての行を字下げするために、このタブ文字が必要です。
連鎖におけるフィルタの順序が重要である点に留意してください。最初のフィルタがキーワードの置換結果に適用され、2つ目の フィルタが最初のフィルタの適用結果に適用される、という具合です。例えば、fill68|tabindent という記述はtabindent|fill68 とは全く違った結果となります。
コマンド行でのテンプレート指定は、手早く簡単に出力を整形する手段を提供します。しかし、テンプレートは冗長に成りがちですか ら、テンプレートに名前付けできれば便利になります。様式(sytle)ファイルは、名前が付けられ、ファイルに保存されたテンプレー トのことです。
それ以上に、コマンド行での--template オプション使用では引き出せなかった Mercurial のテンプレートエンジンの能力を、様 式ファイルを用いることで引き出すことができます。
以下に示す簡単な様式ファイルは、1行だけのものです。
この様式記述は、 “チェンジセットを表示する際には、右辺のテキストをテンプレートとして使用せよ” と Mercurial に指示しま す。
様式ファイルの文法は簡単です。
様式ファイルの記述を説明するために、幾つかの例を示します。様式ファイル一式を通して読むよりも、非所に簡単な例から始めて、幾 つかの複雑な例を通し読みすることで、通常の様式ファイル作成手順を示そうと思います。
様式ファイル中に問題があった場合、 Mercurial はそっけないエラーメッセージを表示しますが、意味するところがわかってしまえ ば、そのメッセージは非常に有用です。
broken.style は、changeset キーワードを定義しようとしているものの、その内容が記述されていない点に注目してください。このような様式ファイルが指定された場合、 Mercurial は即座にメッセージを表示します。
このメッセージは威圧的に見えますが、読み解くのはそれほど難しくありません。
問題の説明は(この例のように)常に明確であるとは限りませんが、暗号めいたものであったとしても、様 式ファイル中の問題となる行を目視確認して間違いを見つける上では、殆どの場合は取るに足らない説明で す。
短い文字列を識別子として Mercurial リポジトリを “概ね一意に” 識 別2 したい 場合、リポジトリの最初のリビジョンを使用するのが良いでしょう。
この値は一意であることが保証されていませんが、それでも多くの場合において有用です。
リポジトリ識別子の利用例を以下に示します。
例えば Subversion のような、他の構成管理ツールのデフォルト出力形式をまねてみましょう。
Subversion の出力様式はかなり単純ですので、出力内容をファイルに保存し、出力テキスト中で Subversion により(動的に)生成される部分を、展 開されるテンプレート値3 で 置き換えるのは容易でしょう。
このテンプレートによる出力が、 Subversion により生成される出力様式から逸脱する場 合4 が幾つ かあります。
Subversion の出力例を元に、上記テンプレートのようなキーワード・フィルタへの置き換えを行う作業は、せいぜいが1〜2分で済む作業です。様式ファイルは、単にこのテンプレートを参照すれば良いのです。
テンプレートファイルテキストを様式ファイルで直接設定するには、引用符で囲み、改行文字を “
n” で置き換えれば良いのですが、様式ファイルを非常に読み難くしてしまいます。テンプレートを様式ファイルに直接記述するか、テ
ンプレートファイルに記述したものを様式ファイルから参照するかを決める際には、可読性を基準とするのが良いでしょう。様式ファイ
ルの大きさや複雑さが高まる場合は、テンプレートテキストを記述するのではなく、外部ファイルに出してしまいましょ
う。