.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Unicode::Stringprep 3"
.TH Unicode::Stringprep 3 "2007-10-06" "perl v5.8.4" "User Contributed Perl Documentation"
.SH "NAME"
Unicode::Stringprep \- Preparation of Internationalized Strings (RFC\ 3454)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Unicode::Stringprep;
\&  use Unicode::Stringprep::Mapping;
\&  use Unicode::Stringprep::Prohibited;
.Ve
.PP
.Vb 11
\&  my $prepper = Unicode::Stringprep->new(
\&    3.2,
\&    [ { 32 => '<SPACE>'},  ],
\&    'KC',
\&    [ @Unicode::Stringprep::Prohibited::C12, @Unicode::Stringprep::Prohibited::C22,
\&      @Unicode::Stringprep::Prohibited::C3, @Unicode::Stringprep::Prohibited::C4,
\&      @Unicode::Stringprep::Prohibited::C5, @Unicode::Stringprep::Prohibited::C6,
\&      @Unicode::Stringprep::Prohibited::C7, @Unicode::Stringprep::Prohibited::C8,
\&      @Unicode::Stringprep::Prohibited::C9 ],
\&    1 );
\&  $output = $prepper->($input)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the \fIstringprep\fR framework for preparing
Unicode text strings in order to increase the likelihood that
string input and string comparison work in ways that make sense
for typical users throughout the world.  The \fIstringprep\fR
protocol is useful for protocol identifier values, company and
personal names, internationalized domain names, and other text
strings.
.PP
The \fIstringprep\fR framework does not specify how protocols should
prepare text strings. Protocols must create profiles of
stringprep in order to fully specify the processing options.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
This module provides a single function, \f(CW\*(C`new\*(C'\fR, that creates a
perl function implementing a \fIstringprep\fR profile.
.PP
This module exports nothing.
.ie n .IP "\fBnew($unicode_version, \fB$mapping_tables\fB, \f(BI$unicode_normalization\fB, \f(CB$prohibited_tables\fB, \f(CB$bidi_check\fB)\fR" 4
.el .IP "\fBnew($unicode_version, \f(CB$mapping_tables\fB, \f(CB$unicode_normalization\fB, \f(CB$prohibited_tables\fB, \f(CB$bidi_check\fB)\fR" 4
.IX Item "new($unicode_version, $mapping_tables, $unicode_normalization, $prohibited_tables, $bidi_check)"
Creates a callable object that implements a stringprep profile.
.Sp
\&\f(CW$unicode_version\fR is the Unicode version specified by the
stringprep profile. Currently, this must be \f(CW3.2\fR.
.Sp
\&\f(CW$mapping_tables\fR provides the mapping tables used for
stringprep.  It may be a reference to a hash or an array. A hash
must map Unicode codepoints (as integers, e.\ g. \f(CW0x0020\fR for
U+0020) to replacement strings (as perl strings).  An array may
contain pairs of Unicode codepoints and replacement strings as
well as references to nested hashes and arrays.
Unicode::Stringprep::Mapping provides the tables from \s-1RFC\s0\ 3454,
Appendix\ B. For further information on the mapping step, see
\&\s-1RFC\s0\ 3454, section\ 3.
.Sp
\&\f(CW$unicode_normalization\fR is the Unicode normalization to be used.
Currently, \f(CW''\fR (no normalization) and \f(CW'KC'\fR (compatibility
composed) are specified for \fIstringprep\fR. For further information
on the normalization step, see \s-1RFC\s0\ 3454, section\ 4.
.Sp
\&\f(CW$prohibited_tables\fR provides the list of prohibited output
characters for stringprep.  It may be a reference to an array. The
array contains pairs of codepoints, which define the start and end
of a Unicode character range (as integers). The end character may
be \f(CW\*(C`undef\*(C'\fR, specifying a single-character range. The array may
also contain references to nested arrays.
Unicode::Stringprep::Prohibited provides the tables from
\&\s-1RFC\s0\ 3454, Appendix C. For further information on the prohibition
checking step, see \s-1RFC\s0\ 3454, section\ 5.
.Sp
\&\f(CW$bidi_check\fR must be set to true if additional checks for
bidirectional characters are required. For further information on
the bidi checking step, see \s-1RFC\s0\ 3454, section\ 6.
.Sp
The function returned can be called with a single parameter, the
string to be prepared, and returns the prepared string. It will
die if the input string is invalid (so use \f(CW\*(C`eval\*(C'\fR if necessary).
.Sp
For performance reasons, it is strongly recommended to call the
\&\f(CW\*(C`new\*(C'\fR function as few times as possible, i.\ e. once per
\&\fIstringprep\fR profile. It might also be better not to use this
module directly but to use (or write) a module implementing a
profile, such as Net::IDN::Nameprep.
.SH "IMPLEMENTING PROFILES"
.IX Header "IMPLEMENTING PROFILES"
You can easily implement a \fIstringprep\fR profile without
subclassing:
.PP
.Vb 1
\&  package ACME::ExamplePrep;
.Ve
.PP
.Vb 1
\&  use Unicode::Stringprep;
.Ve
.PP
.Vb 2
\&  use Unicode::Stringprep::Mapping;
\&  use Unicode::Stringprep::Prohibited;
.Ve
.PP
.Vb 12
\&  *exampleprep = Unicode::Stringprep->new(
\&    3.2,
\&    [ 
\&      \e@Unicode::Stringprep::Mapping::B1, 
\&    ],
\&    '',
\&    [
\&      \e@Unicode::Stringprep::Prohibited::C12,
\&      \e@Unicode::Stringprep::Prohibited::C22,
\&    ],
\&    1,
\&  );
.Ve
.PP
This binds \f(CW\*(C`ACME::ExamplePrep::exampleprep\*(C'\fR to the function
created by \f(CW\*(C`Unicode::Stringprep\->new\*(C'\fR.
.PP
Usually, it is not necessary to subclass this module. Sublassing
this module is not recommended.
.SH "DATA TABLES"
.IX Header "DATA TABLES"
The following modules contain the data tables from \s-1RFC\s0\ 3454.
These modules are automatically loaded when loading
\&\f(CW\*(C`Unicode::Stringprep\*(C'\fR.
.IP "* Unicode::Stringprep::Unassigned" 4
.IX Item "Unicode::Stringprep::Unassigned"
.Vb 1
\&  @Unicode::Stringprep::Unassigned::A1  # Appendix A.1
.Ve
.IP "* Unicode::Stringprep::Mapping" 4
.IX Item "Unicode::Stringprep::Mapping"
.Vb 3
\&  @Unicode::Stringprep::Mapping::B1     # Appendix B.1
\&  @Unicode::Stringprep::Mapping::B2     # Appendix B.2
\&  @Unicode::Stringprep::Mapping::B2     # Appendix B.3
.Ve
.IP "* Unicode::Stringprep::Prohibited" 4
.IX Item "Unicode::Stringprep::Prohibited"
.Vb 11
\&  @Unicode::Stringprep::Prohibited::C11 # Appendix C.1.1
\&  @Unicode::Stringprep::Prohibited::C12 # Appendix C.1.2
\&  @Unicode::Stringprep::Prohibited::C21 # Appendix C.2.1
\&  @Unicode::Stringprep::Prohibited::C22 # Appendix C.2.2
\&  @Unicode::Stringprep::Prohibited::C3  # Appendix C.3
\&  @Unicode::Stringprep::Prohibited::C4  # Appendix C.4
\&  @Unicode::Stringprep::Prohibited::C5  # Appendix C.5
\&  @Unicode::Stringprep::Prohibited::C6  # Appendix C.6
\&  @Unicode::Stringprep::Prohibited::C7  # Appendix C.7
\&  @Unicode::Stringprep::Prohibited::C8  # Appendix C.8
\&  @Unicode::Stringprep::Prohibited::C9  # Appendix C.9
.Ve
.IP "* Unicode::Stringprep::BiDi" 4
.IX Item "Unicode::Stringprep::BiDi"
.Vb 2
\&  @Unicode::Stringprep::BiDi::D1        # Appendix D.1
\&  @Unicode::Stringprep::BiDi::D2        # Appendix D.2
.Ve
.SH "PERL VERSION"
.IX Header "PERL VERSION"
You should use perl 5.8.3 or higher.
.PP
Well, these modules \s-1DO\s0 work with perl 5.6.x. However, \fByou\fR have to make sure
that you only pass valid \s-1UTF\-8\s0 strings to this module or you will get
unintended results. perl 5.8.x (or higher) takes care of this by maintaining a
\&\s-1UTF\-8\s0 flag for strings.
.PP
With perl versions up to 5.8.2, surrogate characters (U+D800..U+DFFF) break
string handling. If a profile tries to map these characters, they won't be
mapped (currently no stringprep profile does this). If a profile prohibits
these characters, this module may fail to detect them (currently, all profiles
do that, so \fByou\fR have to make sure that these characters are not present).
.SH "AUTHOR"
.IX Header "AUTHOR"
Claus Färber <CFAERBER@cpan.org>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Unicode::Normalize, \s-1RFC\s0\ 3454 <http://www.ietf.org/rfc/rfc3454.txt>