=encoding utf8

=head1 NAME

Unicode::LineBreak::JA_JP - UAX #14 ユニコード行分割アルゴリズム

=head1 SYNOPSIS

    use Unicode::LineBreak;
    $lb = Unicode::LineBreak->new();
    $broken = $lb->break($string);

=head1 DESCRIPTION

Unicode::LineBreak は、ユニコード標準の附属書14 [UAX #14] で述べるユニコード行分割アルゴリズムを実行する。
分割位置を決定する際に、附属書11 [UAX #11] で定義される East_Asian_Width 参考属性も考慮する。

B<NOTE>: This is alpha release just for proof-of-concept.


=cut

=head2 公開インタフェース

=over 4

=item new ([KEY => VALUE, ...])

I<コンストラクタ>。
KEY => VALUE の対については L</オプション> を参照。

=back


=cut

=over 4

=item $self->config (KEY)

=item $self->config (KEY => VALUE, ...)

I<インスタンスメソッド>。
設定を取得または変更する。
KEY => VALUE の対については L</オプション> を参照。

=back


=cut

=over 4

=item $self->break (STRING)

I<インスタンスメソッド>。
ユニコード文字列 STRING を分割し、それを返す。

=back

=cut

=over 4

=item getcontext ([Charset => CHARSET], [Language => LANGUAGE])

I<関数>。
キャラクタセット CHARSET および言語コード I<LANGUAGE> から、それを使う言語/地域の文脈を得る。

=back

=cut

=head2 オプション

L<new>、L<config> の両メソッドには以下の対を指定できる。

=over 4

=item Context => CONTEXT

言語/地域の文脈を指定する。
現在使える文脈は C<"EASTASIAN"> か C<"NONEASTASIAN"> である。
初期の文脈は C<"NONEASTASIAN"> である。

=item Format => METHOD

分割した行を整形する方法を指定する。

=over 4

=item C<"DEFAULT">

初期の方法。
任意分割の位置に改行を挿入するだけ。

=item C<"NEWLINE">

Newline オプションで指定したもので改行の文字列を置き換えるか、挿入する。
改行の前とテキスト終端の空白文字を除去する。
テキスト終端に改行がなければ追加する。

=item C<"TRIM">

任意分割の位置に改行を挿入する。
改行の前の空白文字を除去する。

=item サブルーチンへの参照

L</"行分割動作のカスタマイズ"> 参照。

=back

Newline オプションも参照。

=item HangulAsAL => C<"YES"> | C<"NO">

ハングル音節とハングル連結チャモ〔conjoining jamo〕を音素文字的〔alphabetic〕(AL) に扱う。
初期値は C<"NO">。

=item LegacyCM => C<"YES"> | C<"NO">

前に空白文字がついた結合文字を単独の結合文字と扱う。
Unicode 5.0 版からは、空白文字のこのような使いかたは推奨されない。
初期値は C<"YES">。

=item MaxColumns => NUMBER

行の最大桁数 (改行の文字列と行端の空白文字を含めない)。つまり、行の最大長。
初期値は C<76>。

=item Newline => STRING

改行の文字列とするユニコード文字列。
初期値は C<"\n">。

=item NSKanaAsID => C<">CLASS...C<">

CLASS で指定した分類に基づき、一部の行頭禁止文字 (NS) を通常の表語文字的〔ideographic〕な文字 (ID) と扱う。
CLASS には以下の部分文字列を含められる。

=over 4

=item C<"ALL">

下記の文字すべて。
C<"YES"> も同じ。

=item C<"ITERATION MARKS">

表語文字的な繰り返し記号。

注。仮名ではないものもある。

=item C<"KANA SMALL LETTERS">, C<"PROLONGED SOUND MARKS">

小書き仮名、長音記号。

注。これらの文字は行頭禁止文字と扱われることも、通常の表語文字的に扱われることもある。[JIS X 4051] 6.1.1 参照。

=item C<"MASU MARK">

U+303C ます記号。

注。この文字は仮名ではないが、通常 C<"ます"> や C<"マス"> の略記として用いられる。

注。この文字は [UAX #14] では行頭禁止文字 (NS) に分類されるが、[JIS X 4051] では文字クラス (13) (ID に相当) に分類される。

=item C<"NO">

初期値。
以上のいずれの文字も ID と扱わない。

=back

=item SizingMethod => METHOD

文字列の長さを算出する方法を指定する。
以下のオプションが使える。

=over 4

=item C<"DEFAULT">

初期の方法。

=item C<"NARROWAL">

ラテン、ギリシア、キリルの各用字系では、特定の文字が曖昧 (A) の East_Asian_Width 属性を持っている。このため、こういった文字は C<"EASTASIAN"> 文脈で広い文字として扱われる。
このオプションで、そのような文字を狭い文字として扱える。

=item サブルーチンへの参照

L</"行分割動作のカスタマイズ"> を参照。

=back

=back

=head2 行分割動作のカスタマイズ

=head3 行の整形

C<Format> オプションにサブルーチンへの参照を指定する場合、そのサブルーチンは 3 つの引数を取らなければならない。オブジェクトのインスタンス、事象の種類、文字列である。
事象の種類は文字列で、サブルーチンが呼ばれた文脈を表す。
文字列は分割位置の前または後のユニコード文字列の断片である。

    事象  |駆動の契機           |文字列の値
    -----------------------------------------------------------------
    "sot" |テキスト先頭         |最初の行の断片
    "sop" |強制分割の後         |次の行の断片
    "sol" |任意分割の後         |続きの行の断片
    ""    |分割の直前           |行全体 (終端の空白文字を除く)
    "eol" |任意分割             |分割位置の前の空白文字
    "eop" |強制分割             |改行とその前の空白文字
    "eot" |テキスト終端         |テキスト終端の空白文字 (と改行)
    -----------------------------------------------------------------

サブルーチンは、テキストの断片を修正して返さなければならない。なにも修正しなかったことを示すには、C<undef> を返せばよい。
なお、C<"sot">、C<"sop">、C<"sol"> の文脈での修正はその後の分割位置の決定に影響するが、ほかの文脈での修正は影響しない。


=cut

=head3 文字列長の算出

C<Size> オプションにサブルーチンへの参照を指定する場合、そのサブルーチンは 5 つの引数を取らなければならない。オブジェクトのインスタンス、元の文字列の長さ (LEN とする)、元のユニコード文字列 (PRE)、追加される空白文字 (SPC)、追加されるユニコード文字列 (STR) である。

サブルーチンは C<PRE.SPC.STR> の長さを算出して返さなければならない。

=cut

=head3 文字の分類と行分割の基本規則

文字の分類と行分割の基本的な規則は L<Unicode::LineBreak::Data> と L<Unicode::LineBreak::Rules> で定義している。
これらをカスタマイズしたい場合は、ソースパッケージの F<data> ディレクトリの中を見ること。

=cut

=head2 設定ファイル

L</new> メソッドおよび L</config> メソッドのオプション引数の組み込み初期値は、 設定ファイルで上書きできる。
F<Unicode/LineBreak/Defaults.pm>。
詳細は F<Unicode/LineBreak/Defaults.pm.sample> を読んでほしい。

=head2 標準への適合性

このモジュールで用いている文字属性の値は、ユニコード標準 5.1.0 版によるものである。

このモジュールでは、実装水準 UAX14-C2 を実装しているつもりである。

=over 4

=item *

一部の表語文字的な文字を NS として扱うか ID として扱うかを選べる。

=item *

ハングル音節およびハングル連結チャモを ID として扱うか AL として扱うかを選べる。

=item *

AI に分類される文字を AL と ID のどちらに解決するかを選べる。

=item *

CB に分類される文字は解決しない。

=item *

SA に分類される文字は AL に解決する。
ただし、General_Category 属性が Mn か Mc である文字は CM に解決する。

=item *

SG や XX に分類される文字は AL に解決する。

=back

=head1 CAVEAT

I<To be written>.

=head1 BUGS

バグやバグのような動作は、開発者に教えてください。L</AUTHOR> を参照。

=head1 VERSION

$VERSION 変数を参照してほしい。

このモジュールの開発版が
L<http://hatuka.nezumi.nu/repos/Unicode-LineBreak/>
にある。

=head1 REFERENCES

=over 4

=item [JIS X 4051]

JIS X 4051:2004
I<日本語文書の組版方法>.
日本規格協会, 2004.

=begin comment

=item [JLREQ]

阿南康宏・千葉弘幸・枝本順三郎他 (2008).
I<日本語組版処理の要件: W3C 草案 2008年10月15日>.
L<http://www.w3.org/TR/2008/WD-jlreq-20081015/ja/>.

=end comment

=item [UAX #11]

A. Freytag (2008).
I<Unicode Standard Annex #11: East Asian Width>, Revision 17.
L<http://unicode.org/reports/tr11/>.

=item [UAX #14]

A. Freytag and A. Heninger (2008).
I<Unicode Standard Annex #14: Unicode Line Breaking Algorithm>, Revision 22.
L<http://unicode.org/reports/tr14/>.

=back

=head1 SEE ALSO

L<Text::Wrap>.

=head1 AUTHOR

Copyright (C) 2009 Hatuka*nezumi - IKEDA Soji <hatuka(at)nezumi.nu>.

This program is free software; you can redistribute it and/or modify it 
under the same terms as Perl itself.


=cut

