13 our @ISA = qw(Exporter DynaLoader);
15 # Items to export into callers namespace by default. Note: do not export
16 # names by default without a very good reason. Use EXPORT_OK instead.
17 # Do not simply export all your public functions/methods/constants.
19 # This allows declaration use Net::LibIDN ':all';
20 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
22 our %EXPORT_TAGS = ( 'all' => [ qw(
41 IDNA_USE_STD3_ASCII_RULES
44 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
48 IDNA_USE_STD3_ASCII_RULES
50 our $VERSION = '0.07';
52 # avoid prototyping error message
54 sub IDNA_ALLOW_UNASSIGNED
56 return constant("IDNA_ALLOW_UNASSIGNED", length("IDNA_ALLOW_UNASSIGNED"));
59 sub IDNA_USE_STD3_ASCII_RULES
61 return constant("IDNA_USE_STD3_ASCII_RULES", length("IDNA_USE_STD3_ASCII_RULES"));
65 # This AUTOLOAD is used to 'autoload' constants from the constant()
66 # XS function. If a constant is not found then control is passed
67 # to the AUTOLOAD in AutoLoader.
71 ($constname = $AUTOLOAD) =~ s/.*:://;
72 croak "& not defined" if $constname eq 'constant';
73 my $val = constant($constname, @_ ? $_[0] : 0);
78 $AutoLoader::AUTOLOAD = $AUTOLOAD;
79 goto &AutoLoader::AUTOLOAD;
83 croak "Your vendor has not defined Net::LibIDN macro $constname";
88 # Fixed between 5.005_53 and 5.005_61
91 *$AUTOLOAD = sub () { $val };
95 *$AUTOLOAD = sub { $val };
101 bootstrap Net::LibIDN $VERSION;
103 # Preloaded methods go here.
105 # Autoload methods go after =cut, and are processed by the autosplit program.
112 Net::LibIDN - Perl bindings for GNU Libidn
116 use Net::LibIDN ':all';
118 idn_to_ascii("Räksmörgås.Josefßon.ORG") eq
119 idn_to_ascii(idn_to_unicode("xn--rksmrgs-5wao1o.josefsson.org"));
121 idn_prep_name("LibÜDN") eq "libüdn";
123 idn_punycode_encode("kistenmöhre") eq
124 idn_punycode_encode(idn_punycode_decode("kistenmhre-kcb"));
128 tld_check("mèrle.se", $errpos) eq undef;
131 tld_get("mainbase.mars") eq "mars";
133 my $hashref = Net::LibIDN::tld_get_table("de");
135 print "$hashref->{version}\n";
136 foreach (@{$hashref->{valid}})
138 print "Unicode range from ".$_->{start}." to ".$_->{end}."\n";
144 Provides bindings for GNU Libidn, a C library for handling Internationalized
145 Domain Names according to IDNA (RFC 3490), in a way very much inspired by
146 Turbo Fredriksson's PHP-IDN.
152 =item B<Net::LibIDN::idn_to_ascii>(I<$clear_hostname>, [I<$charset>, [I<$flags>]]);
154 Converts I<$clear_hostname> which might contain characters outside
155 the range allowed in DNS names, to IDNA ACE. If I<$charset> is
156 specified, treats string as being encoded in it, otherwise
157 assumes it is ISO-8859-1 encoded. If flag
158 B<IDNA_ALLOW_UNASSIGNED> is set in I<$flags>, accepts also unassigned
159 Unicode characters, if B<IDNA_USE_STD3_ASCII_RULES> is set, accepts
160 only ASCII LDH characters (letter-digit-hyphen). Flags can be
161 combined with ||. Returns result of conversion or B<undef> on
164 =item B<Net::LibIDN::idn_to_unicode>(I<$idn_hostname>, [I<$charset>, [I<$flags>]]);
166 Converts ASCII I<$idn_hostname>, which might be IDNA ACE
167 encoded, into the decoded form in I<$charset> or ISO-8859-1. Flags
168 are interpreted as above. Returns result of conversion
169 or B<undef> on error.
171 =item B<Net::LibIDN::idn_punycode_encode>(I<$string>, [I<$charset>]);
173 Encodes I<$string> into "punycode" (RFC 3492). If I<$charset>
174 is present, treats I<$string> as being in I<$charset>, otherwise
175 uses ISO-8859-1. Returns result of conversion
176 or B<undef> on error.
178 =item B<Net::LibIDN::idn_punycode_decode>(I<$string>, [I<$charset>]);
180 Decodes I<$string> from "punycode" (RFC 3492). If I<$charset>
181 is present, result is converted to I<$charset>, otherwise
182 it is converted to ISO-8859-1. Returns result of conversion
183 or B<undef> on error.
185 =item B<Net::LibIDN::idn_prep_name>(I<$string>, [I<$charset>]);
187 =item B<Net::LibIDN::idn_prep_kerberos5>(I<$string>, [I<$charset>]);
189 =item B<Net::LibIDN::idn_prep_node>(I<$string>, [I<$charset>]);
191 =item B<Net::LibIDN::idn_prep_resource>(I<$string>, [I<$charset>]);
193 =item B<Net::LibIDN::idn_prep_plain>(I<$string>, [I<$charset>]);
195 =item B<Net::LibIDN::idn_prep_trace>(I<$string>, [I<$charset>]);
197 =item B<Net::LibIDN::idn_prep_sasl>(I<$string>, [I<$charset>]);
199 =item B<Net::LibIDN::idn_prep_iscsi>(I<$string>, [I<$charset>]);
201 Performs "stringprep" (RFC 3454) on $string according to the named
202 profile (e.g. *_name -> "nameprep" (RFC 3491)).
203 If I<$charset> is present, converts from and to this charset before and after
204 the operation respectively. Returns result string, or B<undef> on error.
209 =item B<Net::LibIDN::tdl_check>(I<$string>, I<$errpos>, [I<$charset>, [I<$tld>]]);
211 Checks whether or not I<$string> conforms to the restrictions on the sets
212 of valid characters defined by TLD authorities around the World. Treats
213 I<$string> as a hostname if I<$tld> is not present, determining the TLD
214 from the hostname. If I<$tld> is present, uses the restrictions defined
215 by the parties responsible for TLD I<$tld>. I<$charset> may be used to
216 specify the character set the I<$string> is in. Should an invalid character
217 be detected, returns 0 and the 0-based position of the offending character
218 in I<$errpos>. In case of other failure conditions, I<$errpos> is not touched,
219 and B<undef> is returned. Should I<$string> conform to the TLD restrictions,
222 =item B<Net::LibIDN::tld_get>(I<$hostname>);
224 Returns top level domain of I<$hostname>, or B<undef> if an error
225 occurs or if no top level domain was found.
227 =item B<Net::LibIDN::tld_get_table>(I<$tld>);
229 Retrieves a hash reference with the TLD restriction info of given
230 TLD I<$tld>, or B<undef> if I<$tld> is not found. The hash ref contains the
235 =item * I<$h->>I<{name}> ... name of TLD
237 =item * I<$h->>I<{version}> ... version string of this restriction table
239 =item * I<$h->>I<{nvalid}> ... number of Unicode intervals
241 =item * I<$h->>I<{valid}> ... [ {I<start> => number, I<end> => number}, ...] ... Unicode intervals
250 Thomas Jacob, http://internet24.de
254 perl(1), RFC 3454, RFC 3490-3492, http://www.gnu.org/software/libidn.