diff options
author | Karen Etheridge <ether@cpan.org> | 2018-01-08 22:07:28 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-01-08 22:07:28 -0800 |
commit | 4fd548db81539da84c92c89dfa61fbdee952c119 (patch) | |
tree | 1cf2d18024994c6ff2d07400c20e9117f935888a | |
parent | da086d4821d1152e4fd8b73f336cac319f7dc4c2 (diff) | |
parent | 571967cbd998f87f9146fcc3608a711dc933e6d3 (diff) | |
download | uri-4fd548db81539da84c92c89dfa61fbdee952c119.tar.gz |
Merge pull request #46 from libwww-perl/genio-puny-doc
Update the documentation for URI::_punycode
-rw-r--r-- | Changes | 1 | ||||
-rw-r--r-- | lib/URI/_punycode.pm | 68 |
2 files changed, 42 insertions, 27 deletions
@@ -1,6 +1,7 @@ Revision history for URI {{$NEXT}} + - Update documentation for URI::_punycode (GH Issue #45) 1.72 2017-07-25 - Convert the dist to Dist::Zilla for authoring. diff --git a/lib/URI/_punycode.pm b/lib/URI/_punycode.pm index 89233de..ca5ebf2 100644 --- a/lib/URI/_punycode.pm +++ b/lib/URI/_punycode.pm @@ -147,58 +147,72 @@ sub min { 1; __END__ +=encoding utf8 + =head1 NAME URI::_punycode - encodes Unicode string in Punycode =head1 SYNOPSIS - use URI::_punycode; - $punycode = encode_punycode($unicode); - $unicode = decode_punycode($punycode); + use strict; + use warnings; + use utf8; -=head1 DESCRIPTION + use URI::_punycode qw(encode_punycode decode_punycode); -URI::_punycode is a module to encode / decode Unicode strings into -Punycode, an efficient encoding of Unicode for use with IDNA. + # encode a unicode string + my $punycode = encode_punycode('http://☃.net'); # http://.net-xc8g + $punycode = encode_punycode('bücher'); # bcher-kva + $punycode = encode_punycode('他们为什么不说中文'); # ihqwcrb4cv8a8dqg056pqjye -This module requires Perl 5.6.0 or over to handle UTF8 flagged Unicode -strings. + # decode a punycode string back into a unicode string + my $unicode = decode_punycode('http://.net-xc8g'); # http://☃.net + $unicode = decode_punycode('bcher-kva'); # bücher + $unicode = decode_punycode('ihqwcrb4cv8a8dqg056pqjye'); # 他们为什么不说中文 -=head1 FUNCTIONS +=head1 DESCRIPTION -This module exports following functions by default. +L<URI::_punycode> is a module to encode / decode Unicode strings into +L<Punycode|https://tools.ietf.org/html/rfc3492>, an efficient +encoding of Unicode for use with L<IDNA|https://tools.ietf.org/html/rfc5890>. -=over 4 +=head1 FUNCTIONS + +All functions throw exceptions on failure. You can C<catch> them with +L<Syntax::Keyword::Try> or L<Try::Tiny>. The following functions are exported +by default. -=item encode_punycode +=head2 encode_punycode - $punycode = encode_punycode($unicode); + my $punycode = encode_punycode('http://☃.net'); # http://.net-xc8g + $punycode = encode_punycode('bücher'); # bcher-kva + $punycode = encode_punycode('他们为什么不说中文') # ihqwcrb4cv8a8dqg056pqjye -takes Unicode string (UTF8-flagged variable) and returns Punycode +Takes a Unicode string (UTF8-flagged variable) and returns a Punycode encoding for it. -=item decode_punycode +=head2 decode_punycode - $unicode = decode_punycode($punycode) + my $unicode = decode_punycode('http://.net-xc8g'); # http://☃.net + $unicode = decode_punycode('bcher-kva'); # bücher + $unicode = decode_punycode('ihqwcrb4cv8a8dqg056pqjye'); # 他们为什么不说中文 -takes Punycode encoding and returns original Unicode string. +Takes a Punycode encoding and returns original Unicode string. -=back +=head1 AUTHOR -These functions throw exceptions on failure. You can catch 'em via -C<eval>. +Tatsuhiko Miyagawa <F<miyagawa@bulknews.net>> is the author of +L<IDNA::Punycode> which was the basis for this module. -=head1 AUTHOR +=head1 SEE ALSO + +L<IDNA::Punycode>, L<RFC 3492|https://tools.ietf.org/html/rfc3492>, +L<RFC 5891|https://tools.ietf.org/html/rfc5891> -Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt> is the author of -IDNA::Punycode v0.02 which was the basis for this module. +=head1 COPYRIGHT AND LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. -=head1 SEE ALSO - -L<IDNA::Punycode>, RFC 3492 - =cut |