| package Apache::Util; |
| |
| use strict; |
| use mod_perl (); |
| use vars qw($VERSION @EXPORT_OK %EXPORT_TAGS); |
| |
| use Exporter (); |
| use DynaLoader (); |
| |
| *unescape_uri = \&Apache::unescape_url; |
| *unescape_uri_info = \&Apache::unescape_url_info; |
| |
| *import = \&Exporter::import; |
| |
| @EXPORT_OK = qw(escape_html escape_uri unescape_uri unescape_uri_info |
| parsedate ht_time size_string validate_password); |
| %EXPORT_TAGS = (all => \@EXPORT_OK); |
| $VERSION = '1.02'; |
| |
| __PACKAGE__->mod_perl::boot($VERSION); |
| |
| 1; |
| __END__ |
| |
| |
| =head1 NAME |
| |
| Apache::Util - Interface to Apache C util functions |
| |
| =head1 SYNOPSIS |
| |
| use Apache::Util qw(:all); |
| |
| =head1 DESCRIPTION |
| |
| This module provides a Perl interface to some of the C utility functions |
| available in Perl. The same functionality is avaliable in libwww-perl, but |
| the C versions are faster: |
| |
| use Benchmark; |
| timethese(1000, { |
| C => sub { my $esc = Apache::Util::escape_html($html) }, |
| Perl => sub { my $esc = HTML::Entities::encode($html) }, |
| }); |
| |
| Benchmark: timing 1000 iterations of C, Perl... |
| C: 0 secs ( 0.17 usr 0.00 sys = 0.17 cpu) |
| Perl: 15 secs (15.06 usr 0.04 sys = 15.10 cpu) |
| |
| use Benchmark; |
| timethese(10000, { |
| C => sub { my $esc = Apache::Util::escape_uri($uri) }, |
| Perl => sub { my $esc = URI::Escape::uri_escape($uri) }, |
| }); |
| |
| Benchmark: timing 10000 iterations of C, Perl... |
| C: 0 secs ( 0.55 usr 0.01 sys = 0.56 cpu) |
| Perl: 2 secs ( 1.78 usr 0.01 sys = 1.79 cpu) |
| |
| =head1 FUNCTIONS |
| |
| =over 4 |
| |
| =item escape_html |
| |
| This routine replaces unsafe characters in $string with their entity |
| representation. |
| |
| my $esc = Apache::Util::escape_html($html); |
| |
| This function will correctly escape US-ASCII output. If you are using |
| a different character set such as UTF8, or need more control on |
| the escaping process, use HTML::Entities. |
| |
| =item escape_uri |
| |
| This function replaces all unsafe characters in the $string with their |
| escape sequence and returns the result. |
| |
| my $esc = Apache::Util::escape_uri($uri); |
| |
| =item unescape_uri |
| |
| This function decodes all %XX hex escape sequences in the given URI. |
| |
| my $unescaped = Apache::Util::unescape_uri($safe_uri); |
| |
| =item unescape_uri_info |
| |
| This function is similar to unescape_uri() but is specialized to remove |
| escape sequences from the query string portion of the URI. The main |
| difference is that it translates the ``+'' character into spaces as well |
| as recognizing and translating the hex escapes. |
| |
| Example: |
| |
| $string = $r->uri->query; |
| my %data = map { Apache::Util::unescape_uri_info($_) } |
| split /[=&]/, $string, -1; |
| |
| This would correctly translate the query string |
| ``name=Fred+Flintstone&town=Bedrock'' into the hash: |
| |
| name => 'Fred Flintstone', |
| town => 'Bedrock' |
| |
| =item parsedate |
| |
| Parses an HTTP date in one of three standard forms: |
| |
| Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123 |
| |
| Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036 |
| |
| Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format |
| |
| Example: |
| |
| my $secs = Apache::Util::parsedate($date_str); |
| |
| =item ht_time |
| |
| Format a time string. |
| |
| Examples: |
| |
| my $str = Apache::Util::ht_time(time); |
| |
| my $str = Apache::Util::ht_time(time, "%d %b %Y %T %Z"); |
| |
| my $str = Apache::Util::ht_time(time, "%d %b %Y %T %Z", 0); |
| |
| =item size_string |
| |
| Converts the given file size into a formatted string. The size |
| given in the string will be in units of bytes, kilobytes, or |
| megabytes, depending on the size. |
| |
| my $size = Apache::Util::size_string -s $r->finfo; |
| |
| =item validate_password |
| |
| Validate a plaintext password against a smashed one. Use either |
| crypt() (if available), ap_MD5Encode() or ap_SHA1Encode depending |
| upon the format of the smashed input password. |
| |
| Returns true if they match, false otherwise. |
| |
| if (Apache::Util::validate_password("slipknot", "aXYx4GnaCrDQc")) { |
| print "password match\n"; |
| } |
| else { |
| print "password mismatch\n"; |
| } |
| |
| =back |
| |
| =head1 AUTHOR |
| |
| Doug MacEachern |
| |
| =head1 SEE ALSO |
| |
| perl(1). |
| |
| =cut |