
=encoding utf-8

=head1 NAME

Unicode::Precis::Preparation~[ja] - RFC 8264 PRECISフレームワーク - 準備

=head1 SYNOPSIS

  use Unicode::Precis::Preparation qw(prepare IdentifierClass);
  $result = prepare($string, IdentifierClass);
  %result = prepare($string, IdentifierClass);

=head1 DESCRIPTION

L<Unicode::Precis::Preparation>は、PRECIS
フレームワークに従ってユニコード文字列またはUTF-8のバイト文字列の準備を行う。

なお当ドキュメントでは、「UTF-8」という語を本来の意味で用いる。

=head2 Function

=over

=item prepare ( $string, [ $stringclass ], [ UnicodeVersion =E<gt> $version ] )

文字列が指定した文字列クラスに適合するか検査する。

Parameters:

=over

=item $string

検査する文字列。ユニコード文字列かバイト文字列。

バイト文字列は、ユニコードへアップグレードされることなく
UTF-8列として扱われることに注意。

=item $stringclass

C<ValidUTF8> (初期値)、C<FreeFormClass>
(RFC 8264参照)、C<IdentifierClass> (同) のいずれか。

=item UnicodeVersion =E<gt> $version

ユニコードの版を与えると、それに従ってレパートリを制限する。
初期状態では、当モジュールを使うPerl
が対応しているユニコードの版のレパートリが使われる。

=back

Returns:

スカラコンテキストでは、
指定した文字列クラスに適合すれば真値。そうでなければ偽値。

配列コンテキストでは、
次のキーを持つ対によるリストで結果の詳細を返す。

=over

=item C<result>

L</Constants>で述べる特性値のいずれか。

=item C<offset>

検査が失敗したときは、文字列の先頭からのオフセット。
成功したときは、文字列の長さ。

オフセットや長さは、
バイト文字列ではバイト数、ユニコード文字列では文字数で数える。

=item C<length>

検査が失敗したときの、認められない文字の長さ。
長さは、バイト文字列ではC<1>からC<4>、ユニコード文字列では常にC<1>、
不正な列では未定義となる。

=item C<ord>

C<length>がある場合、文字のユニコードスカラ値。

=back

=back

=head2 Constants

=over

=item FreeFormClass

=item IdentifierClass

=item ValidUTF8

文字列クラス。C<ValidUTF8>は当モジュールによる拡張である。

=item UNASSIGNED

=item PVALID

=item CONTEXTJ

=item CONTEXTO

=item DISALLOWED

結果を示す特性値。C<PVALID>は成功を意味する。

=back

=head2 Exports

初期状態ではなにもエクスポートしない。
C<:all> タグで prepare()および定数をエクスポートする。

=head1 CAVEATS

=head2 ユニコードの版

=over

=item 文字列クラス

導出特性はユニコード6.3.0以降に基づく。
文字によってはユニコード6.0.0より前と非互換な特性値を持つ (RFC 6452も参照)。
一方、ユニコード6.3.0以後に追加された文字の特性値は将来変わるかもしれない。

=item 文脈規則

文脈規則が参照する文字の特性は、Perl
の最近の版が対応しているユニコードの版に基づく。
文字によってはユニコード6.3.0と非互換な特性値を持つ。

=back

=head1 RESTRICTIONS

prepare()はEBCDICプラットフォームでのユニコード文字列を検査できない。

=head1 SEE ALSO

L<Unicode::Precis>

RFC 8264 I<PRECIS Framework: Preparation, Enforcement, and Comparison of
Internationalized Strings in Application Protocols>.
L<https://tools.ietf.org/html/rfc8264>.

=head1 AUTHOR

Hatuka*nezumi - IKEDA Soji, E<lt>hatuka@nezumi.nuE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015, 2018, 2025 by Hatuka*nezumi - IKEDA Soji

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. For more details, see the full text of
the licenses at <http://dev.perl.org/licenses/>.

This program is distributed in the hope that it will be
useful, but without any warranty; without even the implied
warranty of merchantability or fitness for a particular purpose.

=cut
