=encoding utf8

=head1 NAME

VCS::Lite - 最低限のバージョンコントロールシステム

=head1 SYNOPSIS

  use VCS::Lite;

  # diff

  my $lit = VCS::Lite->new('/home/me/foo1.txt');
  my $lit2 = VCS::Lite->new('/home/me/foo2.txt');
  my $difftxt = $lit->delta($lit2)->diff;
  print OUTFILE $difftxt;

  # patch

  my $delt = VCS::Lite::Delta->new('/home/me/patch.diff');
  my $lit3 = $lit->patch($delt);
  print OUTFILE $lit3->text;

  # merge

  my $lit4 = $lit->merge($lit->delta($lit2),$lit->delta($lit3));
  print OUTFILE $lit4->text;

=head1 DESCRIPTION

このモジュールは、バージョンコントロールシステムと、一般に関連のある機能を提供します。
ですが、バージョンコントロールシステムを必要も、実装もしません。
用途は、wiki や、ドキュメントマネージメントシステムや設定マネージメントを含みます。

VCS::Lite は、Algorithm::Diffモジュールを使います。
Algorithm::Diffは、基本的な、diffing、pathing、merging の機能を提供します。

=head2 new

VCS::Lite の基礎をなすオブジェクトは配列です。
配列のメンバはスカラーが表現できるものなら何でもあり得ます(構造やオブジェクトへのリファレンスを含みます)。
デフォルトでは、オブジェクトは、テキストの行に一致する文字列としてのスカラーの配列です。
もし、他の基礎をなす型がいいなら、VCS::Lite のサブクラスにするのが普通です。
そうすれば、一目瞭然になるからです。

コンストラクタの基本的な形は以下のようになります:

  my $lite = VCS::Lite->new( '/my/file');

これは、ファイルを飲みこんで、オブジェクトを作成します。
完全な形は以下のようになります:

  my $lite = VCS::Lite->new( $object_id, $separator, $source, ...);

ここでいう $object_id は、文字列で、アプリケーションの環境で、diffされたり、pacheされたり、mergeされたりするものを特定する文字列です。

ここでいう $separator は、正規表現で、文字列をトークンに分割するものです。
デフォルトでは、自然の Perl のメカニズムの $/ です。
(これは、ファイルから読まないときにエミュレートされます)。
結果として生じるVCS::Liteオブジェクトは、デフォルトでは、chompされません。

$source が、もし、指定されなければ、$object_id は、ファイルとして開かれ、その完全な内容が行ごとに読まれます。
別の方法は、$source を提供することです。
$source は、下記のようなものです:

=over 4

=item *
スカラー - 文字列で、$separatorでトークン化されます。

=item *
配列リファレンス - トークンの配列です。

=item *
ファイルハンドルかグロブリファレンス - ファイルの内容が読み込まれます

=item *
コールバック - undefを受け取るまで、トークンを得るために連続して呼ばれます

=back

DWIM の Perl魂では、new は配列リファレンスを想定します。
あなたが、何でもリストを作る仕事を終えているなら(訳註：you have already done all the work of making your list of whatevers.)。
文字列(ファイル名)か、ファイルハンドルであれば、
ファイルは飲み込まれ、テキストの行ごとに読んで、配列のメンバに入ります。
コールバックであれば、ルーチンは、引き続いた、引数 $p1、 $p2 ...と一緒に、呼ばれます。
そして、ルーチンは配列に加えられるスカラーを返すことが期待されます。

=head2 apply

  $lite->apply($lite2);
  $lite->apply($lite3, base => 'original');

This method call corresponds approximately to a version control system's
check-in function. This causes $lite to be modified, so that its contents
now reflect those of $lite2.

このメソッド呼び出しは、バージョン管理システムのcheck-in機能とほぼ同等です。
これは$liteへの変更をおこない、結果、この内容は現在$lite2の内容が反映されたものになっています。

$liteはLを通して利用可能な(<オリジナルの>)オリジナルのコンテンツを保有します。 
しかしながら、バージョン制御システムなどと異なって、オブジェクトは最初のオリジナ
ルの、そして、最新のコンテンツだけを保持します。

$liteは元々のコンテンツを保持しており、L<original>を介してアクセスできます。ただし、バージョン制御システムなどと異なり、オブジェクトは最初のオリジナルと最新のコンテンツだけを保持します。

VCS:、:また、渡されたLiteオブジェクトはそれ自身のオリジナルバージョンを持つこ
とができます。 これがそうであるなら、合併は、まるで異なったブランチから来たか
のように変化を取り入れるために実行されるでしょう。 合併しているプロセスを
facilitiateするには、任意にストリング'オリジナル'、'コンテンツ'(デフォルト)ま
たはVCSであるかもしれないベースバージョンを指定してください:、:コンテンツが使
用されるLiteは反対します。
これはバージョン制御システムの「一般的な先祖」に対応しています。

渡されたVCS::Liteオブジェクトも自身のオリジナルバージョンを持つことができます。もしこのケースで、マージはこれが別のブランチから来た変更であっても取り込もうとするでしょう。
マージを容易にするには、オプションでベースとなるバージョンを指定します。文字列で'string'、'contents'（デフォルト）、またはそのコンテンツを採用してよいVCS::Liteオブジェクトを指定できます。
これはバージョン管理システムの「一般的な先祖」に対応しています。

=head2 text

  my $foo = $lite->text;
  my $bar = $lit2->text('|');
  my @baz = $lit3->text;

スカラーコンテキストでは、飲み込まれたファイル内容と等しいものを返します（オプションのセパレータは文字列を一つに結合する使われ、$_がデフォルトとして採用されます）。リストコンテキストでは、行か、レコードのリストを返します。

=head2 id

  my $fil = $lite->id

newでVCS::Lite要素が生成された時に関連付けられた名前を返します。通常はファイル名です。

=head2 delta

  my $delt = $lit->delta($lit2);

2つの、VCS::Lite オブジェクト間の差分を取ります。
このオブジェクトは、L<VCS::Lite::Delta>オブジェクトを返します。

=head2 patch

  my $lit3 = $lit->patch($delt);

VCS::Lite オブジェクトへパッチを適用します。
ファイルハンドルか、ファイル名の文字列を受け取ります。
ファイルをdiff フォーマットとみなして読み込み、それを適用します。
パッチ済みソースに対応する VCS::Lite オブジェクトを返します。

=head2 merge

  my $lit4 = $lit->merge($lit1,$lit2,\&confl);

"平行四辺形のマージ"を行います。これはVCS::Lite オブジェクトであらわされた二つの変更の流れを適用します。両方の変更がマージされたVCS::Lite オブジェクトを返します。

このメソッドへの三番目のパラメータは、マージ中にコンフリクト（衝突）が起きたときに呼び出されるサブルーチンです。これはコンフリクトを解決するか、コンフリクトがあったことがはっきりするように解決不可のテキストを挿入するべきです。

=head1 COPYRIGHT

Copyright (c) Ivor Williams, 2002-2005

=head1 LICENCE

You may use, modify and distribute this module under the same terms 
as Perl itself.

=head1 SEE ALSO

L<Algorithm::Diff>.

=head1 DOCUMENT TRANSLATION

Makio Tsukamoto, tsukamoto@gmail.com

=cut