#language ja

このページは [[GraphvizExtension]] の翻訳です。

== Graphviz 拡張 ==

'''この拡張は、Mercurial と共には配布されません。'''

''著者: Katsunori FUJIWARA''

=== 概要 ===

この拡張は、
チェンジセットツリーを可視化するための
([[http://www.graphviz.org/|Graphviz]] の) DOT 言語ソースを生成します。

Graphviz は、
画像（例：{{{*.jpg}}}）ファイルだけでなく、
クライアントサイドのイメージマップも生成できますので、
{{{hg serve}}} と連携する HTML ページを得ることもできます。

Mercurial 0.9.3 ～ 0.9.5 上で動作確認済みの Graphviz 拡張は、
http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/graphviz.py から入手可能です
(2008-02-19 に更新されました)。
描画例を
http://www.lares.dti.ne.jp/~foozy/fujiguruma/scm/hg-visualize.html
で見ることができます。

=== 設定 ===

{{{graphviz.py}}} を python が認識しているディレクトリ配下に配置した場合、
以下の行を設定ファイル({{{hgrc}}})に追加することで、
この拡張を有効にすることができます。

{{{
[extensions]
graphviz = 
}}}

それ以外の場合は:

{{{
[extensions]
graphviz = /path/to/graphviz.py
}}}

=== 利用方法 ===

{{{
hg graphviz [OPTIONS] [limit-spec ...]
}}}

'''{{{limit-spec}}}''' を指定しない場合、
{{{graphviz}}} は全てのチェンジセットを描画対象とみなします。

描画対象チェンジセットは、
'''リビジョン範囲'''(''-r'' オプション参照) 、
'''日時範囲'''(''-d'' オプション参照)ないし
'''間隔範囲'''(''-i'' オプション参照)の何れかで制限できます。

'''リビジョン範囲'''に対しては、
'リビジョン番号'、'tip への相対番号'、
'短縮チェンジセットID'、'チェンジセットID'
ないし'タグ名'のいずれも指定可能です。

'''日付範囲'''に対しては、
''YYYY-MM-DDThh:mm:ss''(中間の '''T''' は '''T''' そのものでなくてはなりません)
として知られる XML Schema dateTime フォーマットを使用する必要があります。
しかし、それほど強い制約が掛けられているわけではありませんので、
例えば {{{2007-99-99T99:99:99}}} のような指定も可能です。

'''間隔範囲'''に対しては、
コマンド起動時刻からの間隔を'''秒'''で指定する必要があります。

{{{limit-spec}}} は３つの形式のうちのどれかでなければなりません。

  1. '{{{Start,End}}}' 形式は対象チェンジセットを
  '{{{Start}}}' から '{{{End}}}' の間のものに限定します。

  1. '{{{Start,}}}' 形式は対象チェンジセットを
  '{{{Start}}}' 以後のものに限定します。

  1. '{{{,End}}}' 形式は対象チェンジセットを
  '{{{End}}}' 以前のものに限定します。

'''注意:''' {{{End}}} は'''含む'''ものとみなされますので、
例えば 2007 年より後に生成されたチェンジセットを無視する場合は、
{{{2007-12-31T24:00:00}}} のようなものを指定する必要があります。

{{{graphviz}}} は以下のオプションを認識します。

{{{
 -r --revision           use revision to limit targets(default)
 -d --datetime           use datetime to limit targets
 -i --interval           use interval from NOW to limit targets
 -a --aliases            file with user name aliases
    --show-tags          show tags in graph
 -u --urlbase            url base for client side image map
    --format-label       format of changeset label (default: %(r)s)
    --format-tooltip     format of changeset tooltip (default: %(U)s/%(t)s)
    --group-by-date      group changesets per date
    --group-by-branch    group changesets per branch
    --node-attr-hook     hook to render node attribute
    --edge-attr-hook     hook to render edge attribute
    --cluster-attr-hook  hook to render cluster attribute
}}}

=== ユーザ名エイリアス ===

ユーザ名がラベルの一部として使用された際にラベル長を低減するために、
エイリアス設定ファイルを指定することができます。
このファイルは、以下の形式の行か、
''#'' で始まるコメント行で構成されていなければなりません。

{{{
AliasName=ActualName
}}}


=== ラベル/ツールチップのフォーマット ===

描画されるチェンジセットのラベルとツールチップ
（例えば、クライアントサイドイメージマップで使用されます）
のフォーマットの両方を指定することができます。

フォーマット文字列は、
Python スタイルのフォーマット形式で、
以下のキーワードを使用することができます。
全てのキーワードは文字列と置換されます。

    * u: ユーザ名(エイリアスで置換され得ます)
    * U: ユーザ名(エイリアス置換されません)
    * r: チェンジセットリビジョン番号
    * s: 短縮形式のチェンジセットハッシュ値(12 桁の 16 進)
    * h: チェンジセットハッシュ値(40 桁の 16 進)
    * d: チェンジセットの日付
    * t: チェンジセットコメント文の最初の一行

例えば、'{{{%(u)s|%(r)s}}}' というフォーマット文字列は
'{{{commiter|revision#}}}' という結果になります。


=== グループ化 ===

グループ化、とりわけ''日付による''グループ化は、
感覚的に適切な位置にチェンジセットを描画するかもしれません。

{{{group-by-date}}} オプションを指定した場合、
graphviz 拡張はチェンジセットを日付ごとにグループ化します。
このグループ化により、日付ごとの矩形が描画されるようになります。

{{{group-by-branch}}} オプションを指定した場合、
graphviz 拡張はチェンジセットを、
'{{{default}}}' ブランチを除くブランチごとにグループ化します。
このグループ化により、ブランチごとの矩形が描画されるようになります。

上記の矩形を隠蔽したい場合、
'''描画のカスタマイズ'''を参照してください。


=== 描画のカスタマイズ ===

グラフ描画を制御するフックオプションが３つあります。

それぞれのオプションは２つの形式を受け付けます。

    * '{{{lambda }}}' で始まる文字列は、即席の関数定義とみなされます

    - *.py ファイルをロードするための完全修飾された Python 関数名
      (例: {{{module.name.function}}})

フックが空文字列か None を返した場合、
graphviz 拡張は描画対象に対して属性を付加しません。

==== (1) ノード(node)属性フック ====

このフックは各ノードに属性を追加でき、
以下に示すシグネチャを持っている必要があります。

{{{
def hook(repository, revision, node, changes, getalias):
}}}

各引数は:

    * repo     : 対象リビジョンが属するリポジトリ
    * rev      : リビジョン番号
    * node     : '{{{repo.lookup(rev)}}}' で得られたもの
    * changes  : '{{{repo.changelog.rev(node)}}}' で得られたもの
    * getalias : 名前からエイリアス変換するための '{{{lambda name:}}}'

例えば、以下のようなコードにより、
特定のユーザによるチェンジセットを強調することができます。

{{{
def hook(repo, rev, node, changes, getalias):
    return ((getalias(changes[1]) == 'someone')
            and 'style = "filled", fontcolor = "white"'
            or None)
}}}

=== (2) エッジ(edge)属性フック ===

このフックは各エッジに属性を追加でき、
以下に示すシグネチャを持っている必要があります。

{{{
def hook(repo, parent, child, first, getalias):
}}}

各引数は:

    * repo     : 対象リビジョンが属するリポジトリ
    * parent   : エッジの描画元
    * child    : エッジの描画先
    * first    : parent が child にとって第一親か否か
    * getalias : 名前からエイリアス変換するための '{{{lambda name:}}}'

{{{parent}}} および {{{child}}} は共に
{{{(rev, node, changes)}}} というタプルなので、
エッジ属性フックを以下のように定義することもできます。

{{{
def hook(repo, (pr, pn, pc), (cr, cn, cc), first, getalias):
}}}

==== (3) クラスタ(cluster)属性フック ====

このフックは各クラスタ（＝グループ化矩形）に属性を追加でき、
以下に示すシグネチャを持っている必要があります。

{{{
def hook(repo, branch, date)
}}}

各引数は:

    * repo     : 対象リビジョンが属するリポジトリ
    * branch   : ブランチ名
    * date     : 日付文字列({{{YYYYMMDD}}} 形式)ないし {{{""}}}

{{{group-by-branch}}} オプションを指定した場合、
'{{{default}}}' 以外の各ブランチごとにこのフックが起動されます。
起動時には、{{{""}}} が日付として指定されます。

{{{group-by-date}}} オプションを指定した場合、
各日付ごとにブランチ名付き
（'{{{default}}}' の場合も）でこのフックが起動されます。

'{{{group-by-date}}}' と '{{{group-by-branch}}}' 
のいずれのオプションも指定されない場合、
このフックは起動されません。

例えば、以下のようなコードにより、
全てのグループ化矩形を非表示にすることができます。

{{{
def hook(repo, branch, date):
    return 'style=invis'
}}}

あるいは、ブランチのグループ化矩形のみを表示するには:

{{{
def hook(repo, branch, date):
    return (date and 'style=invis')
}}}

Graphviz DOT 言語仕様に適合するために、
他のフックが '{{{,}}}' で区切られた値を返すのと異なり、
このフックは '{{{;}}}' で区切られた値を返す必要があります。


=== Mercurial 向けフック ===

画像ファイルを自動的に更新するために、
graphviz 拡張は {{{hook}}} 関数も提供しています。
このフックはフック種別に依存した引数を使用していないので、
任意のフックに指定することができます。
しかし、
最も有用なのは {{{changegroup}}}/{{{commit}}} フックに使用した場合でしょう。

{{{
[hooks]
changegroup = python:graphviz.hook
commit = python:graphviz.hook
}}}

{{{hgrc}}} ファイルの {{{graphviz}}} セクションによって、
フックの挙動を制御できます。

{{{
[graphviz]
# REQUIRED: 画像ファイル出力先
imagefile=%%(hgroot)s/.hg/revtree.jpg

# opt.* は対応するコマンドラインオプションの指定と等価です
opt.revision=
#opt.datetime=
#opt.interval=
opt.aliases=%%(hgroot)s/aliases
opt.show-tags=
opt.urlbase=http://localhsot:8000
opt.format-label=%%(r)s
opt.format-tooltip=%%(U)s/%%(t)s
opt.group-by-date=
opt.group-by-branch=
#opt.node-attr-hook=
opt.edge-attr-hook=fully.qualified.python.function
opt.cluster-attr-hook=lambda repo, branch, date: 'style=invis'

# 制限指定リスト
limitspecs=-50,

# Graphviz DOT コマンドのコマンドラインオプション
dot_opts=-Nfontsize=9 -Grankdir=BT

# 指定した場合、DOT 言語ソースを保存。
# 'imagefile' ファイルと同じ場所に '*.dot' サフィックスで保存
dot_source=

# 指定した場合、クライアントサイドイメージマップを生成。
# 'imagefile' と同じ場所に '*.html' サフィックスで保存
imagemap=

# イメージマップ HTML ファイルの導入(= '<img> タグ'の前)部分
prologue=<html><head><title>last updated by %%(r)s</title>....

# イメージマップ HTML ファイルの結び(= '<area> タグ'の後)部分
epilogue=....</html>
}}}

上記の例からわかるように、
幾つかの設定中にはキーワード置換を指定することができます。
しかし、
設定ファイル読み込みにおける Python ライブラリの自動置換を抑止するために、
通常の Python 記述における {{{%}}} の代わりに {{{%%}}} を用いる必要があります。

{{{format-label}}} および {{{format-tooltip}}}
向けの全てのキーワードが利用可能ですが、
それらの値は tip チェンジセットのものが使用されます。

それに加えて、以下のキーワードも使用可能です。

  * now: フック起動日時
  * hgroot: 対象リポジトリのルート位置

キーワード置換は以下のものに適用されます。

  * imagefile
  * opt.aliases
  * prologue
  * epilogue


=== フックの手動起動 ===

{{{graphviz-hook}}} コマンドにより、
graphviz 拡張のフックを手動で起動できます。

これにより、commit/pull すること無しに、
フック設定を確認することができます。
----
CategoryJapanese