vcs.maemo.org Git - pkg-perl/blob - deb-src/libnet-libidn-perl/libnet-libidn-perl-0.07/_LibIDN.pm

   1 package Net::LibIDN;
   2
   3 use 5.006;
   4 use strict;
   5 use warnings;
   6 use Errno;
   7 use Carp;
   8
   9 require Exporter;
  10 require DynaLoader;
  11 use AutoLoader;
  12
  13 our @ISA = qw(Exporter DynaLoader);
  14
  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.
  18
  19 # This allows declaration       use Net::LibIDN ':all';
  20 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
  21 # will save memory.
  22 our %EXPORT_TAGS = ( 'all' => [ qw(
  23         idn_to_ascii
  24         idn_to_unicode
  25         idn_punycode_encode
  26         idn_punycode_decode
  27         idn_prep_name
  28         idn_prep_kerberos5
  29         idn_prep_node
  30         idn_prep_resource
  31         idn_prep_plain
  32         idn_prep_trace
  33         idn_prep_sasl
  34         idn_prep_iscsi
  35 #IF_TLD
  36         tld_check
  37         tld_get
  38         tld_get_table
  39 #ENDIF_TLD
  40         IDNA_ALLOW_UNASSIGNED
  41         IDNA_USE_STD3_ASCII_RULES
  42 ) ] );
  43
  44 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
  45
  46 our @EXPORT = qw(
  47         IDNA_ALLOW_UNASSIGNED
  48         IDNA_USE_STD3_ASCII_RULES
  49 );
  50 our $VERSION = '0.07';
  51
  52 # avoid prototyping error message
  53
  54 sub IDNA_ALLOW_UNASSIGNED
  55 {
  56         return constant("IDNA_ALLOW_UNASSIGNED", length("IDNA_ALLOW_UNASSIGNED"));
  57 }
  58
  59 sub IDNA_USE_STD3_ASCII_RULES
  60 {
  61         return constant("IDNA_USE_STD3_ASCII_RULES", length("IDNA_USE_STD3_ASCII_RULES"));
  62 }
  63
  64 sub AUTOLOAD {
  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.
  68
  69         my $constname;
  70         our $AUTOLOAD;
  71         ($constname = $AUTOLOAD) =~ s/.*:://;
  72         croak "& not defined" if $constname eq 'constant';
  73         my $val = constant($constname, @_ ? $_[0] : 0);
  74         if ($! != 0)
  75         {
  76                 if ($!{EINVAL})
  77                 {
  78                 $AutoLoader::AUTOLOAD = $AUTOLOAD;
  79                 goto &AutoLoader::AUTOLOAD;
  80                 }
  81                 else
  82                 {
  83                 croak "Your vendor has not defined Net::LibIDN macro $constname";
  84                 }
  85         }
  86         {
  87                 no strict 'refs';
  88                 # Fixed between 5.005_53 and 5.005_61
  89                 if ($] >= 5.00561)
  90                 {
  91                         *$AUTOLOAD = sub () { $val };
  92                 }
  93                 else
  94                 {
  95                         *$AUTOLOAD = sub { $val };
  96                 }
  97         }
  98         goto &$AUTOLOAD;
  99 }
 100
 101 bootstrap Net::LibIDN $VERSION;
 102
 103 # Preloaded methods go here.
 104
 105 # Autoload methods go after =cut, and are processed by the autosplit program.
 106
 107 1;
 108 __END__
 109
 110 =head1 NAME
 111
 112 Net::LibIDN - Perl bindings for GNU Libidn
 113
 114 =head1 SYNOPSIS
 115
 116   use Net::LibIDN ':all';
 117
 118   idn_to_ascii("Räksmörgås.Josefßon.ORG") eq
 119     idn_to_ascii(idn_to_unicode("xn--rksmrgs-5wao1o.josefsson.org"));
 120
 121   idn_prep_name("LibÜDN") eq "libüdn";
 122
 123   idn_punycode_encode("kistenmöhre") eq
 124     idn_punycode_encode(idn_punycode_decode("kistenmhre-kcb"));
 125 #IF_TLD
 126
 127   my $errpos;
 128   tld_check("mèrle.se", $errpos) eq undef;
 129     $errpos == 1;
 130
 131   tld_get("mainbase.mars") eq "mars";
 132
 133   my $hashref = Net::LibIDN::tld_get_table("de");
 134
 135   print "$hashref->{version}\n";
 136   foreach (@{$hashref->{valid}})
 137   {
 138     print "Unicode range from ".$_->{start}." to ".$_->{end}."\n";
 139   }
 140 #ENDIF_TLD
 141
 142 =head1 DESCRIPTION
 143
 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.
 147
 148 =head2 Functions
 149
 150 =over 4
 151
 152 =item B<Net::LibIDN::idn_to_ascii>(I<$clear_hostname>, [I<$charset>, [I<$flags>]]);
 153
 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
 162 error.
 163
 164 =item B<Net::LibIDN::idn_to_unicode>(I<$idn_hostname>, [I<$charset>, [I<$flags>]]);
 165
 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.
 170
 171 =item B<Net::LibIDN::idn_punycode_encode>(I<$string>, [I<$charset>]);
 172
 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.
 177
 178 =item B<Net::LibIDN::idn_punycode_decode>(I<$string>, [I<$charset>]);
 179
 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.
 184
 185 =item B<Net::LibIDN::idn_prep_name>(I<$string>, [I<$charset>]);
 186
 187 =item B<Net::LibIDN::idn_prep_kerberos5>(I<$string>, [I<$charset>]);
 188
 189 =item B<Net::LibIDN::idn_prep_node>(I<$string>, [I<$charset>]);
 190
 191 =item B<Net::LibIDN::idn_prep_resource>(I<$string>, [I<$charset>]);
 192
 193 =item B<Net::LibIDN::idn_prep_plain>(I<$string>, [I<$charset>]);
 194
 195 =item B<Net::LibIDN::idn_prep_trace>(I<$string>, [I<$charset>]);
 196
 197 =item B<Net::LibIDN::idn_prep_sasl>(I<$string>, [I<$charset>]);
 198
 199 =item B<Net::LibIDN::idn_prep_iscsi>(I<$string>, [I<$charset>]);
 200
 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.
 205
 206
 207 #IF_TLD
 208
 209 =item B<Net::LibIDN::tdl_check>(I<$string>, I<$errpos>, [I<$charset>, [I<$tld>]]);
 210
 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,
 220 1 is returned.
 221
 222 =item B<Net::LibIDN::tld_get>(I<$hostname>);
 223
 224 Returns top level domain of I<$hostname>, or B<undef> if an error
 225 occurs or if no top level domain was found.
 226
 227 =item B<Net::LibIDN::tld_get_table>(I<$tld>);
 228
 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
 231 following fields:
 232
 233 =over 4
 234
 235 =item * I<$h->>I<{name}> ... name of TLD
 236
 237 =item * I<$h->>I<{version}> ... version string of this restriction table
 238
 239 =item * I<$h->>I<{nvalid}> ... number of Unicode intervals
 240
 241 =item * I<$h->>I<{valid}> ...  [ {I<start> => number, I<end> => number}, ...] ... Unicode intervals
 242
 243 =back
 244
 245 #ENDIF_TLD
 246 =back
 247
 248 =head1 AUTHOR
 249
 250 Thomas Jacob, http://internet24.de
 251
 252 =head1 SEE ALSO
 253
 254 perl(1), RFC 3454, RFC 3490-3492, http://www.gnu.org/software/libidn.
 255
 256 =cut